From a5e2dfdcf34f53dd876bb3965beb264ff927a72b Mon Sep 17 00:00:00 2001
From: marshawcoco <marshawcoco@gmail.com>
Date: Wed, 24 Jun 2026 17:09:33 +0000
Subject: [PATCH 1/7] feat(gc): publish gc and prune commands

Signed-off-by: marshawcoco <marshawcoco@gmail.com>
---
 COMPATIBILITY.md                              |   2 +
 README.md                                     |   5 +-
 docs/commands/README.md                       |   2 +
 docs/commands/gc.md                           |  14 +-
 docs/commands/maintenance.md                  |   2 +-
 docs/commands/prune.md                        |  11 +-
 docs/commands/zh-CN/README.md                 |   2 +
 docs/commands/zh-CN/prune.md                  |  39 ++++++
 docs/development/commands/README.md           |   4 +-
 docs/development/commands/_compatibility.md   |   4 +-
 docs/development/commands/gc.md               |  26 ++++
 docs/development/commands/prune.md            |  27 ++++
 docs/development/integration-scenarios.yaml   |   4 +-
 .../_parameter-tables.md                      |   2 +-
 .../integration-scenarios/cli.gc-smoke.md     |  14 +-
 docs/development/internal/gc.md               |  25 ++--
 docs/development/internal/prune.md            |  23 ++-
 src/cli.rs                                    |   6 +
 src/command/agent/clean.rs                    |  12 +-
 src/command/gc.rs                             |  77 +++++-----
 src/command/mod.rs                            |   2 +
 src/command/prune.rs                          |  34 +++--
 src/command/verify_pack.rs                    |  12 ++
 .../ai/context_budget/compaction_agent.rs     |   3 +-
 src/utils/client_storage.rs                   |  22 +++
 tests/command/agent_push_test.rs              |   8 +-
 tests/command/mod.rs                          |   2 +
 tests/command/prune_test.rs                   | 132 +++++++++++++++++-
 .../publish_ai_object_model_contract_test.rs  |   2 +-
 29 files changed, 393 insertions(+), 125 deletions(-)
 create mode 100644 docs/commands/zh-CN/prune.md
 create mode 100644 docs/development/commands/gc.md
 create mode 100644 docs/development/commands/prune.md

diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md
index 85f97c584..0476bcce0 100644
--- a/COMPATIBILITY.md
+++ b/COMPATIBILITY.md
@@ -73,6 +73,8 @@ batch document.
 | open | supported | |
 | config | partial | vault-backed local/global config is supported; system scope, editor round-trip, typed conversion, NUL output, section rename/remove, and includeIf are incomplete |
 | op | intentionally-different | Libra command-level operation history inspection/restore extension, not a Git command |
+| gc | partial | Traces reachable objects, expires reflogs, prunes eligible unreachable loose objects, and cleans stale pack sidecar files; `--dry-run`, `--prune=<date>`, `--no-prune`, `--aggressive` (accepted no-op), `--auto` (accepted no-op), `--force`, JSON, and machine output supported. Valid pack/index pairs are verified, but Libra does not repack, delta-compress, create cruft packs, or rewrite valid packfiles |
+| prune | partial | Removes eligible unreachable loose objects, with `-n`/`--dry-run`, `-v`/`--verbose`, `--expire <time>`, extra head arguments, JSON, and machine output supported. Prefer `gc` for normal housekeeping; direct prune still has Git-like concurrent-writer caveats |
 | reflog | supported | `show`/`delete`/`exists`/`expire` subcommands. `expire` prunes by time + reachability + `--stale-fix` (`--all`/`--expire`/`--expire-unreachable`/`--rewrite`/`--updateref`/`-n`/`-v`), reads `gc.reflogExpire`/`gc.reflogExpireUnreachable` (90/30-day defaults, never written). Intentional differences: no-ref expire is an explicit error (exit 128) vs Git's silent no-op; `--stale-fix` checks only that the new value loads as a commit (no transitive object walk); `--updateref` skips symbolic `HEAD` / remote-tracking refs |
 | worktree | intentionally-different | `remove` keeps disk dir by default (no implicit data loss). Use `--delete-dir` for Git-style behavior; the flag refuses on a dirty worktree. `worktree list --porcelain` emits a Git-style machine-readable list (`worktree <path>` + the shared `HEAD <sha>` + `locked [<reason>]`); Libra worktrees share one HEAD/index/refs, so Git's per-worktree `branch`/`detached` lines are intentionally omitted |
 | cloud | intentionally-different | Libra cloud backup/restore extension, not a Git command |
diff --git a/README.md b/README.md
index 0cd5f9656..0e9949b74 100644
--- a/README.md
+++ b/README.md
@@ -605,14 +605,11 @@ Note:
 
 The following Git top-level commands are currently **not implemented** in Libra (excluding `submodule` and `subtree`, which are intentionally omitted):
 
-- `gc` – garbage-collect unreachable objects and pack files
-- `prune` – remove loose objects that are no longer reachable
 - `pack-objects` / `unpack-objects` – pack and unpack object collections
-- `remote show <name>`-style detailed inspection – show detailed remote info
 - `fetch-pack` / `push-pack` – low-level fetch/push operations
 - `filter-branch` (or `git filter-repo`) – rewrite history
 
-These commands are slated for future implementation according to the project roadmap. (Several commands once listed here are now implemented — `maintenance`, `notes` (add/append/copy/edit/show/list/remove), and `archive` — and have moved out of this list.) The full per-command compatibility status (`supported` / `partial` / `unsupported` / `intentionally-different`) is tracked in [`COMPATIBILITY.md`](COMPATIBILITY.md).
+These commands are slated for future implementation according to the project roadmap. Several commands once listed here are now implemented — `gc`, `prune`, `maintenance`, `remote show <name>`, `notes` (add/append/copy/edit/show/list/remove), and `archive` — and have moved out of this list. The full per-command compatibility status (`supported` / `partial` / `unsupported` / `intentionally-different`) is tracked in [`COMPATIBILITY.md`](COMPATIBILITY.md).
 
 ## Note on Submodule and Subtree
 
diff --git a/docs/commands/README.md b/docs/commands/README.md
index 29d6718e6..dae465112 100644
--- a/docs/commands/README.md
+++ b/docs/commands/README.md
@@ -114,7 +114,9 @@ Every Libra command accepts the following global flags:
 |---------|-------|-------------|-----|
 | `libra cat-file` | | Inspect Git objects and AI objects by type, size, or pretty-printed content | [cat-file.md](cat-file.md) |
 | `libra fsck` | | Verify the integrity of objects, refs, and index in a Libra repository | [fsck.md](fsck.md) |
+| `libra gc` | | Prune unreachable loose objects and clean stale pack sidecar files | [gc.md](gc.md) |
 | `libra hash-object` | | Compute Git-compatible blob object IDs from files or standard input | [hash-object.md](hash-object.md) |
+| `libra prune` | | Remove unreachable loose objects from the repository | [prune.md](prune.md) |
 | `libra verify-pack` | | Validate pack index files against their pack archives | [verify-pack.md](verify-pack.md) |
 | `libra show-ref` | | List local refs (branches, tags, HEAD) and their object IDs | [show-ref.md](show-ref.md) |
 | `libra symbolic-ref` | | Read or update the symbolic HEAD ref | [symbolic-ref.md](symbolic-ref.md) |
diff --git a/docs/commands/gc.md b/docs/commands/gc.md
index 231736fc5..dacffbdc1 100644
--- a/docs/commands/gc.md
+++ b/docs/commands/gc.md
@@ -1,12 +1,6 @@
 # `libra gc`
 
-Historical design for pruning unreachable loose objects and cleaning stale pack sidecar files.
-
-> Status: unpublished. `libra gc` is not registered in the public CLI in the
-> current release. Running it returns the standard unknown-command error
-> (`LBR-CLI-001`). Use `libra maintenance run --dry-run --task gc` for the
-> currently published maintenance entry point. The notes below describe preserved
-> design material, not a user-visible `gc` command contract.
+Prune unreachable loose objects and clean stale pack sidecar files.
 
 ## Synopsis
 
@@ -16,7 +10,7 @@ libra gc [--dry-run] [--prune=<date> | --no-prune] [--aggressive] [--auto] [--fo
 
 ## Description
 
-The unpublished design first expires reflogs using the default `gc.reflogExpire` and
+`libra gc` first expires reflogs using the default `gc.reflogExpire` and
 `gc.reflogExpireUnreachable` policy, then traces objects reachable from
 repository references, remaining reflogs, the index, in-progress operation
 state, and local AI catalogs. It prunes unreachable loose objects that match the
@@ -75,7 +69,7 @@ Cleaned 0 stale pack file(s).
 
 ## Structured Output
 
-If this command is published in a future release, `--json` should return a `gc` envelope containing:
+With `--json`, `libra gc` returns a `gc` envelope containing:
 
 - `loose_objects.scanned`, `reachable`, `unreachable`, `pruned`, and `retained`
 - `reflogs.refs_scanned`, `entries_scanned`, `pruned`, and `rewritten`
@@ -126,7 +120,7 @@ If this command is published in a future release, `--json` should return a `gc`
 
 ## Compatibility
 
-The unpublished design aligns with Git's core safety rule: reachable objects are retained,
+`libra gc` aligns with Git's core safety rule: reachable objects are retained,
 and unreachable loose objects are pruned only when the prune policy allows it.
 Before pruning objects, Libra runs the same default policy as
 `libra reflog expire --all` without `--rewrite`, `--updateref`, or
diff --git a/docs/commands/maintenance.md b/docs/commands/maintenance.md
index 2e45af089..429e0be8f 100644
--- a/docs/commands/maintenance.md
+++ b/docs/commands/maintenance.md
@@ -104,5 +104,5 @@ libra --json maintenance status
 
 ## See Also
 
-- [`libra gc`](./gc.md) (not yet implemented)
+- [`libra gc`](./gc.md)
 - [`libra fsck`](./fsck.md)
diff --git a/docs/commands/prune.md b/docs/commands/prune.md
index eb22de0a7..49a8a2b4b 100644
--- a/docs/commands/prune.md
+++ b/docs/commands/prune.md
@@ -1,11 +1,6 @@
 # `libra prune`
 
-Historical design for pruning unreachable objects from the repository.
-
-> Status: unpublished. `libra prune` is not registered in the public CLI in the
-> current release. Running it returns the standard unknown-command error
-> (`LBR-CLI-001`). The interface below describes preserved design material, not
-> a user-visible command contract.
+Prune unreachable loose objects from the repository.
 
 ## Synopsis
 
@@ -15,7 +10,7 @@ libra prune [OPTIONS] [HEAD]...
 
 ## Description
 
-The unpublished design effectively runs `libra fsck --unreachable` using all the refs available in `refs/`, optionally with an additional set of heads specified on the command line, and prunes all unpacked objects unreachable from any of these head objects from the repository. In addition, it prunes the unpacked objects that are also found in packs.
+`libra prune` effectively runs `libra fsck --unreachable` using all the refs available in `refs/`, optionally with an additional set of heads specified on the command line, and prunes all unpacked objects unreachable from any of these head objects from the repository. In addition, it prunes the unpacked objects that are also found in packs.
 
 Specifically, unreachable objects found in pack will be kept. For more details about unreachable objects, refer to the `libra fsck --unreachable` documentation.
 
@@ -102,7 +97,7 @@ warnings and errors on stderr.
 
 ## Structured Output
 
-If this command is published in a future release, `libra prune` should support the global `--json` and `--machine` flags on successful prunes.
+`libra prune` supports the global `--json` and `--machine` flags on successful prunes.
 
 - `--json` writes one success envelope to `stdout`
 - `--machine` writes the same schema as compact single-line JSON
diff --git a/docs/commands/zh-CN/README.md b/docs/commands/zh-CN/README.md
index 7c53856d3..7cdd66857 100644
--- a/docs/commands/zh-CN/README.md
+++ b/docs/commands/zh-CN/README.md
@@ -114,7 +114,9 @@
 |------|------|------|------|
 | `libra cat-file` | | 按类型、大小或漂亮打印内容检查 Git 对象和 AI 对象 | [cat-file.md](cat-file.md) |
 | `libra fsck` | | 校验 Libra 仓库中对象、refs 和索引的完整性 | [fsck.md](fsck.md) |
+| `libra gc` | | 清理不可达 loose object 和陈旧 pack 辅助文件 | [gc.md](gc.md) |
 | `libra hash-object` | | 从文件或标准输入计算 Git 兼容 blob 对象 ID | [hash-object.md](hash-object.md) |
+| `libra prune` | | 从仓库移除不可达 loose object | [prune.md](prune.md) |
 | `libra verify-pack` | | 对照 pack 归档验证 pack index 文件 | [verify-pack.md](verify-pack.md) |
 | `libra show-ref` | | 列出本地 refs（分支、标签、HEAD）及其对象 ID | [show-ref.md](show-ref.md) |
 | `libra symbolic-ref` | | 读取或更新符号 HEAD 引用 | [symbolic-ref.md](symbolic-ref.md) |
diff --git a/docs/commands/zh-CN/prune.md b/docs/commands/zh-CN/prune.md
new file mode 100644
index 000000000..0d7daeecb
--- /dev/null
+++ b/docs/commands/zh-CN/prune.md
@@ -0,0 +1,39 @@
+# `libra prune`
+
+从仓库中删除不可达的 loose object。
+
+## 概要
+
+```bash
+libra prune [OPTIONS] [HEAD]...
+```
+
+## 说明
+
+`libra prune` 会从仓库 refs 和可选的额外 `HEAD` 参数出发计算可达对象，然后删除不可达且符合过期策略的 loose object。日常维护优先使用 [`libra gc`](./gc.md)，因为 `gc` 还会处理 reflog 过期和 pack 辅助文件清理。
+
+## 选项
+
+| 标志 | 短选项 | 说明 |
+|------|--------|------|
+| `--dry-run` | `-n` | 只报告将删除的对象，不实际删除 |
+| `--verbose` | `-v` | 输出删除的对象 |
+| `--expire <TIME>` | | 只删除早于指定时间的 loose object |
+| `[HEAD]...` | | 额外保留从这些对象可达的对象 |
+
+## 示例
+
+```bash
+libra prune
+libra prune -n
+libra prune -v --expire "2 weeks ago"
+libra prune HEAD~2
+```
+
+## 结构化输出
+
+支持全局 `--json` 和 `--machine`。成功时输出 `prune` 信封，包含 `objects`、`expire`、`heads`、`dry_run` 和 `verbose`。
+
+## 注意事项
+
+直接运行 prune 与 Git 一样有并发写入风险：如果另一个进程刚写入对象但尚未创建引用，prune 可能删除它仍要使用的 loose object。建议先用 `--dry-run` 预览，并在直接运行时搭配 `--expire`。
diff --git a/docs/development/commands/README.md b/docs/development/commands/README.md
index 395d90f82..be30b8508 100644
--- a/docs/development/commands/README.md
+++ b/docs/development/commands/README.md
@@ -44,6 +44,7 @@
 | [`for-each-ref`](for-each-ref.md) | `partial` | `--heads` / `--tags` / `--remotes` / `--all` / `--format` / `--sort` (`refname`/`objectname`/`version:refname`, each reversible) / `--count` / `--points-at` / `--contains` / `--no-contains` / `--merged` / `--no-merged` / `--exclude` / `<pattern>` supported; full Git atom language, remaining sort keys, and shell quoting modes are not exposed |
 | [`format-patch`](format-patch.md) | `partial` | `-o`/`--output-directory`, `--stdout`, `-n`/`--numbered`, `--start-number`, `--subject-prefix`, `--cover-letter`, `--thread`/`--no-thread`, `--in-reply-to`, `-v`/`--reroll-count`, `-s`/`--signoff`, `--full-index`, `--no-stat`, `--keep-subject`, `--suffix`, `--zero-commit`, `--signature`/`--no-signature`, `--signature-file`, `--encode-email-headers`/`--no-encode-email-headers`, `--numbered-files`, and `A..B`/single-commit revision range supported; merge commits are skipped; `--attach`, `--inline`, `--from`, `--to`, `--cc`, `--base`, `--interdiff`, `--range-diff`, `--notes`, and `--force` are not exposed |
 | [`fsck`](fsck.md) | `partial` | object/ref/index/reflog/connectivity checks supported; JSON/machine output, strict mode and pack verification surface incomplete |
+| [`gc`](gc.md) | `partial` | reachable-object tracing, reflog expiry, eligible loose-object pruning, stale pack sidecar cleanup, JSON/machine output, and accepted `--aggressive`/`--auto` no-ops supported; valid packs are verified but not rewritten or repacked |
 | [`graph`](graph.md) | `intentionally-different` | Libra AI graph inspection extension, not a Git command |
 | [`grep`](grep.md) | `partial` | tracked/index/tree search with common match flags, context lines, `-E`/`-G`, `-P` rejection, `-a`/`-I` binary controls, `--heading`/`--break`/`-z` output grouping, `-m`/`--max-count`, and `-o`/`--only-matching` supported; untracked/no-index search not exposed |
 | [`hash-object`](hash-object.md) | `partial` | Blob hashing for files, `--stdin`, and `--stdin-paths`; `-w` writes blob objects; `--path` / `--no-filters` accepted for raw-byte... |
@@ -61,6 +62,7 @@
 | [`notes`](notes.md) | `partial` | `add` / `append` / `copy` / `edit` / `show` / `list` / `remove` supported; `--ref` supported; merge/prune and the interactive editor not implemented |
 | [`op`](op.md) | `intentionally-different` | Libra command-level operation history inspection/restore extension, not a Git command |
 | [`open`](open.md) | `supported` | 见命令文档。 |
+| [`prune`](prune.md) | `partial` | removes eligible unreachable loose objects with dry-run, verbose, expire, extra head arguments, and JSON/machine output; direct use retains Git-like concurrent-writer caveats |
 | [`publish`](publish.md) | `intentionally-different` | Libra Cloudflare publish extension, not a Git command |
 | [`pull`](pull.md) | `partial` | fetch + fast-forward/three-way merge supported; `--ff-only` / `--rebase` / `--no-rebase` (countermands `--rebase`, last wins) / `--ff` / `--no-ff`, fetch `--depth`, `--squash`, `--no-commit`, `--commit`, `--autostash`, and `--no-progress` (forwarded to the fetch) exposed |
 | [`push`](push.md) | `partial` | branch/tag update, multi-refspec, delete (`-d`/`--delete`), `--tags`, and `--mirror` supported; local file remote rejected — intentiona... |
@@ -90,9 +92,7 @@
 
 以下命令曾有开发设计资料，但已明确决定不接入公开 CLI；它们降级为内部历史资料，不承诺用户可见兼容面：
 
-- `gc`：功能由 `libra maintenance run --task gc` 覆盖（见 `docs/development/internal/gc.md`）
 - `package`：内部设计资料保留（见 `docs/development/internal/package.md`）
-- `prune`：内部设计资料保留（见 `docs/development/internal/prune.md`）
 - `stats`：内部设计资料保留（见 `docs/development/internal/stats.md`）
 
 若未来需要发布其中任一命令，必须重新走完整的 CLI 接入、`COMPATIBILITY.md` 登记、用户文档和回归测试流程。
diff --git a/docs/development/commands/_compatibility.md b/docs/development/commands/_compatibility.md
index fe844052f..3de2b4283 100644
--- a/docs/development/commands/_compatibility.md
+++ b/docs/development/commands/_compatibility.md
@@ -37,7 +37,7 @@ flowchart TD
 
 | 命令 | 当前 tier | 治理结论 | 说明 |
 |---|---|---|---|
-| merge | partial | partial | fast-forward and single-head three-way merge supported; `-m`/`--ff-only`/`--no-ff`/`--squash`/`--no-commit`/`--no-edit` supported; octopus/custom strategies and `--verify-signatures` deferred |
+| merge | partial | partial | fast-forward and single-head three-way merge supported; octopus/custom strategies/squash deferred |
 | pull | partial | partial | fetch + fast-forward/three-way merge supported; advanced strategy flags still partial |
 | push | partial | partial | branch/tag update, multi-refspec, delete, `--tags`, and `--mirror` supported; local file remote rejected intentionally |
 | checkout | partial | partial | visible branch compatibility surface plus explicit `checkout -- <path>` restoration alias; prefer `switch` / `restore` |
@@ -48,7 +48,7 @@ flowchart TD
 
 | 范围 | 全局未实现项 | 代码核对 | 最后确认/处理 |
 |---|---|---|---|
-| 命令接入治理 | `gc`、`package`、`prune`、`stats` 的开发文档或源码文件存在，但用户可见 CLI 与 `COMPATIBILITY.md` 未公开。 | `for-each-ref`、`ls-files`、`ls-tree`、`archive` 和 `notes` 已在 `src/cli.rs::Commands`、`COMPATIBILITY.md` 和命令开发文档中公开，不能再列为未公开命令。其余命令仍需按当前 CLI surface 核对是否返回 `LBR-CLI-001` 或应降级为内部资料。 | 作为全局未收口项保留；后续必须二选一：接入 CLI 并同步 `COMPATIBILITY.md`、命令文档和集成场景，或把对应命令文档降级为内部/历史资料。 |
+| 命令接入治理 | `package`、`stats` 的开发文档或源码文件存在，但用户可见 CLI 与 `COMPATIBILITY.md` 未公开。 | `for-each-ref`、`ls-files`、`ls-tree`、`archive`、`notes`、`gc` 和 `prune` 已在 `src/cli.rs::Commands`、`COMPATIBILITY.md` 和命令文档中公开，不能再列为未公开命令。其余命令仍需按当前 CLI surface 核对是否返回 `LBR-CLI-001` 或应降级为内部资料。 | 作为全局未收口项保留；后续必须二选一：接入 CLI 并同步 `COMPATIBILITY.md`、命令文档和集成场景，或把对应命令文档降级为内部/历史资料。 |
 | 兼容证据治理 | 参数级缺口不能只停留在文字说明；需要在命令开发文档、用户文档和 compat/integration 测试之间闭环。 | 删除独立参数 YAML 后，不再存在 `test_evidence`/`last_verified` 字段；证据必须落到具体测试、脚本或 D 编号说明中。 | 不允许把未验证参数当作完成承诺；新增兼容项时补测试证据，或把状态改为拒绝、延后、有意差异并给出 D 编号。 |
 | 拒绝/延后决策 | submodule family、本地 file remote push、Git hooks bridge、clone recurse-submodules、Git LFS filter/hooks bridge、bisect replay/terms、stash create/store、sparse checkout、patch mode、interactive rebase/todo、clean pathspec、empty commit message。 | 对应 D1-D10、D15、D16、D-clean-pathspec、D-empty-message；源码/CLI 未暴露或显式拒绝这些 surface。 | 维持 D 编号；只有出现明确需求、设计和测试方案时再重启。 |
 | staging/worktree Git surface | `add --intent-to-add`、`clean -i`、`clean <pathspec>`、`restore --overlay/--ours/--theirs/--merge/--progress`、`reset --merge/--keep`、`rm --sparse`、`checkout -p` 以及跨命令 patch mode。 | `mv -k` / `--skip-errors` 已实现，`mv --sparse` 已作为 no-op 暴露；`add`、`clean`、`restore`、`reset`、`rm` 的参数结构仍未暴露这些剩余 flag；patch mode 由 D15 拒绝；`switch --detach` 已实现，不能再把 detached HEAD 作为全局缺口。 | 作为命令级 Git 兼容缺口保留；实现时同步命令文档、`COMPATIBILITY.md` 和 integration scenarios。 |
diff --git a/docs/development/commands/gc.md b/docs/development/commands/gc.md
new file mode 100644
index 000000000..ff0099225
--- /dev/null
+++ b/docs/development/commands/gc.md
@@ -0,0 +1,26 @@
+# `libra gc`
+
+## 命令实现目标
+
+`libra gc` 公开安全的仓库垃圾回收入口：过期 reflog、追踪可达对象、删除符合策略的不可达 loose object，并清理陈旧 pack 辅助文件。
+
+## 当前状态
+
+- 兼容级别：`partial`。
+- 入口：`src/cli.rs::Commands::Gc`。
+- 实现：`src/command/gc.rs`。
+- 用户文档：[`docs/commands/gc.md`](../../commands/gc.md)。
+- 详细设计资料：[`docs/development/internal/gc.md`](../internal/gc.md)。
+
+## 已实现
+
+- `--dry-run` / `--prune=<date>` / `--no-prune` / `--force`。
+- `--aggressive` / `--auto` 作为 Git 兼容 no-op 接受。
+- JSON / machine 输出。
+- 复用 `verify-pack` 校验有效 pack/index 配对。
+
+## 还未实现的功能
+
+| 类别 | 未完成项 | 当前处理 |
+|---|---|---|
+| pack 重写 | 不 repack、delta-compress、创建 cruft pack 或重写有效 packfile。 | 保持 `partial`；需要独立设计和测试。 |
diff --git a/docs/development/commands/prune.md b/docs/development/commands/prune.md
new file mode 100644
index 000000000..c7a89590e
--- /dev/null
+++ b/docs/development/commands/prune.md
@@ -0,0 +1,27 @@
+# `libra prune`
+
+## 命令实现目标
+
+`libra prune` 公开低层对象清理入口，用于删除从 refs 和额外 head 参数都不可达、且符合过期策略的 loose object。
+
+## 当前状态
+
+- 兼容级别：`partial`。
+- 入口：`src/cli.rs::Commands::Prune`。
+- 实现：`src/command/prune.rs`。
+- 用户文档：[`docs/commands/prune.md`](../../commands/prune.md)。
+- 详细设计资料：[`docs/development/internal/prune.md`](../internal/prune.md)。
+
+## 已实现
+
+- `-n` / `--dry-run`。
+- `-v` / `--verbose`。
+- `--expire <TIME>`。
+- `[HEAD]...` 额外保留根。
+- JSON / machine 输出。
+
+## 还未实现的功能
+
+| 类别 | 未完成项 | 当前处理 |
+|---|---|---|
+| 并发 writer 保护 | 直接 prune 仍保留 Git-like 并发 writer 风险。 | 用户文档提示优先 dry-run 与 `--expire`；日常维护优先 `libra gc`。 |
diff --git a/docs/development/integration-scenarios.yaml b/docs/development/integration-scenarios.yaml
index 2d4a72bdd..cb2a3b52a 100644
--- a/docs/development/integration-scenarios.yaml
+++ b/docs/development/integration-scenarios.yaml
@@ -402,10 +402,10 @@ scenarios:
   - id: cli.gc-smoke
     wave: 2
     group: maintenance
-    purpose: "Document current top-level gc/prune command gaps while covering reachable plumbing around unreachable loose blobs and the supported `maintenance run --dry-run --task gc` JSON path, then verifies connectivity."
+    purpose: "Cover public top-level gc/prune dry-run behavior around unreachable loose blobs plus the supported `maintenance run --dry-run --task gc` JSON path, then verifies connectivity."
     gh_required: false
     requires_git: false
-    key_assertion_categories: [json_envelope, fsck, negative_exit, lbr_error]
+    key_assertion_categories: [json_envelope, fsck]
     doc_section: "cli.gc-smoke"
   - id: cli.archive-smoke
     wave: 2
diff --git a/docs/development/integration-scenarios/_parameter-tables.md b/docs/development/integration-scenarios/_parameter-tables.md
index ba2599d10..3c321df12 100644
--- a/docs/development/integration-scenarios/_parameter-tables.md
+++ b/docs/development/integration-scenarios/_parameter-tables.md
@@ -206,7 +206,7 @@
 | `for-each-ref --points-at <object>` | `cli.object-readback` | 指向指定对象的 branch、lightweight tag、annotated tag 可观察 |
 | `rev-list HEAD` / multi revision / `A..B` / `^A` / `A...B` / `--count` / `-n` / `--skip` / `--since` / `--after` / `--until` / `--before` / `--first-parent` / `--author` / `--committer` / `--grep` / `-- <path>` / `--left-right` / `--left-only` / `--right-only` / `--cherry-pick` / `--cherry-mark` / `--cherry` / `--children` | `cli.object-readback` | 可达提交输出、范围/排除、计数/限制、时间过滤、first-parent、author、committer、message grep、path limitation、side/cherry 过滤、children 元数据和 JSON envelope 可观察 |
 | `fsck` / `fsck --connectivity-only` / `fsck <object>` | `cli.object-readback`、`cli.gc-smoke` | 默认、连通性和指定对象检查可观察 |
-| `gc` / `prune` | `cli.gc-smoke` | 当前顶层命令未注册，runner 断言 JSON unknown-command 错误 |
+| `gc --dry-run` / `prune --dry-run` | `cli.gc-smoke` | 当前顶层命令已公开，runner 断言成功 JSON envelope 和 dry-run 标记 |
 | `maintenance run --dry-run --task gc` | `cli.gc-smoke` | 当前可用 maintenance 路径返回 JSON envelope |
 | `archive` | `cli.archive-smoke` | 当前未注册，runner 断言 JSON unknown-command 错误 |
 | `verify-pack [-v|-s] [--pack <pack>] <idx>...` | `cli.verify-pack-smoke` | idx/pack 对应校验、多 index sibling 推导、verbose 对象行、stat-only 摘要和 `--pack` 多 idx 拒绝路径可观察 |
diff --git a/docs/development/integration-scenarios/cli.gc-smoke.md b/docs/development/integration-scenarios/cli.gc-smoke.md
index 667180532..062ef1a9a 100644
--- a/docs/development/integration-scenarios/cli.gc-smoke.md
+++ b/docs/development/integration-scenarios/cli.gc-smoke.md
@@ -1,6 +1,6 @@
 ### `cli.gc-smoke`
 
-目的：覆盖 `gc` 与同族维护命令 `prune` 当前未公开的 Git 兼容命令状态，确保它们不会被误当作已发布 CLI；runner 同时验证已发布的 `maintenance run --dry-run --task gc` 入口仍返回成功 JSON envelope，并在场景末尾验证仓库健康。
+目的：覆盖已公开的 `gc` 与同族维护命令 `prune` 基础 dry-run 行为，确保它们能在含 unreachable loose blob 的仓库中返回成功 JSON envelope；runner 同时验证 `maintenance run --dry-run --task gc` 入口仍返回成功 JSON envelope，并在场景末尾验证仓库健康。
 
 最小步骤：
 
@@ -23,17 +23,19 @@ printf 'gc unreachable blob\n' > unreachable.txt
 OID="$(libra hash-object -w unreachable.txt)"
 libra cat-file -t "$OID" | grep '^blob$'
 
-! libra --json gc --dry-run
-! libra --json prune --dry-run
+libra --json gc --dry-run >gc.json
+python3 -c "import json; d=json.load(open('gc.json')); assert d['ok'] is True; assert d['data']['dry_run'] is True"
+libra --json prune --dry-run >prune.json
+python3 -c "import json; d=json.load(open('prune.json')); assert d['ok'] is True; assert d['data']['dry_run'] is True"
 libra --json maintenance run --dry-run --task gc >maintenance-gc.json
 python3 -c "import json; d=json.load(open('maintenance-gc.json')); assert d['ok'] is True"
 libra fsck --connectivity-only
 ```
 
-断言：`gc` 和 `prune` 当前未注册为顶层命令；`libra --json gc --dry-run` 与 `libra --json prune --dry-run` 必须非 0 退出，JSON 错误码为 `LBR-CLI-001`；`maintenance run --dry-run --task gc` 必须成功；操作后 `libra fsck --connectivity-only` 通过。
+断言：`gc` 和 `prune` 当前已注册为顶层命令；`libra --json gc --dry-run` 与 `libra --json prune --dry-run` 必须 0 退出并返回 `ok:true` 的 JSON envelope；`maintenance run --dry-run --task gc` 必须成功；操作后 `libra fsck --connectivity-only` 通过。
 
 补充可执行断言：
-- `libra --json gc --dry-run` 必须失败，错误码为 `LBR-CLI-001`。
-- `libra --json prune --dry-run` 必须失败，错误码为 `LBR-CLI-001`。
+- `libra --json gc --dry-run` 必须成功，且 `data.dry_run` 为 `true`。
+- `libra --json prune --dry-run` 必须成功，且 `data.dry_run` 为 `true`。
 - `libra --json maintenance run --dry-run --task gc` 必须 `ok:true`。
 - 操作后 `libra fsck --connectivity-only` 通过。
diff --git a/docs/development/internal/gc.md b/docs/development/internal/gc.md
index cc7b855ff..9e0d3ec99 100644
--- a/docs/development/internal/gc.md
+++ b/docs/development/internal/gc.md
@@ -1,24 +1,24 @@
-# `libra gc` 内部设计资料
+# `libra gc` 设计资料
 
-> Status: **declined / historical**. This command was not published to the public CLI.
-> The maintenance entry point `libra maintenance run --task gc` provides the same safe garbage-collection pass.
+> Status: **public / partial**. `libra gc` is registered in the public CLI.
+> `libra maintenance run --task gc` remains available as the scheduled maintenance entry point.
 
-This document preserves the original design notes for the unpublished `gc` implementation. It is not a user-visible command contract and is not tracked in `COMPATIBILITY.md`.
+This document preserves implementation design notes for `gc`. The user-visible command contract is tracked in [`docs/commands/gc.md`](../../commands/gc.md) and [`COMPATIBILITY.md`](../../../COMPATIBILITY.md).
 
 ## 命令实现目标
 
-`libra gc` 的目标是提供安全的仓库维护入口，用于清理不可达对象或执行保守维护任务。当前实现资料存在但顶层 CLI 尚未公开接入，因此目标是先保留安全维护语义，再决定是否进入公开命令面。
+`libra gc` 的目标是提供安全的仓库维护入口，用于清理不可达对象或执行保守维护任务。当前顶层 CLI 已公开接入。
 
 ## 对比 Git 与兼容性
 
-- 兼容级别：`unpublished`。未进入 COMPATIBILITY.md；以代码接入状态为准。
+- 兼容级别：`partial`。以 `COMPATIBILITY.md` 与用户命令文档为准。
 
-- 该资料未对应公开 CLI 命令；用户可见状态按未发布处理。
+- 该资料对应公开 CLI 命令；本文只保留实现设计和维护背景。
 
 
 ## 设计方案
 
-- 入口与分发：源码资料存在但尚未公开接入 `src/cli.rs::Commands`；`src/` 树中没有任何 `mod gc` 声明（`src/command/mod.rs` 未声明该模块），该文件尚未被编译进二进制。CLI 层在 `src/cli.rs` 把解析后的参数交给命令模块，命令模块负责把领域错误转换为 `CliError` / `CliResult`。
+- 入口与分发：`src/cli.rs::Commands::Gc` 公开接入顶层命令，`src/command/mod.rs` 导出 `gc` 模块。CLI 层在 `src/cli.rs` 把解析后的参数交给命令模块，命令模块负责把领域错误转换为 `CliError` / `CliResult`。
 - 源码分层：主要实现文件为 `src/command/gc.rs`。参数/子命令类型包括：`GcArgs`；输出、错误或状态类型包括：源码未暴露独立输出/错误类型，错误通过 `CliResult` 或上层命令错误统一传播；主要执行函数包括：`execute`、`execute_safe`。
 - 执行路径：`execute_safe` 负责 CLI 安全包装、错误映射和输出配置；索引路径会加载、比较、刷新或保存 `.libra/index`；对象路径会解析 revision 并读写 blob/tree/commit/tag 等对象；引用路径会读取或更新 SQLite refs、HEAD 与 reflog；网络路径会解析 remote 配置、协商协议并处理 pack/idx 数据；数据库路径会通过 SeaORM/SQLite 持久化元数据。
 
@@ -42,12 +42,12 @@ flowchart TD
 
 - 本节依据本地 main 分支提交历史重写，筛选与该命令实现、测试或文档路径直接相关的提交；以下是归纳后的实现脉络。
 - 2026-06-10 `a4bbe28b`（`feat(gc): add safe repository maintenance command (#386)`）：基础实现节点：add safe repository maintenance command (#386)；当前实现的主要轮廓可追溯到该提交。
-- 历史结论：`src/command/gc.rs` 或配套测试/文档已有历史节点，但当前 `src/cli.rs::Commands` 未公开 `gc` 入口；实现历史不改变当前状态章节中的未接入结论。
+- 历史结论：`src/command/gc.rs` 或配套测试/文档已有历史节点，当前 `src/cli.rs::Commands` 已公开 `gc` 入口。
 
 ## 当前状态
 
-- 公开状态：未公开；模块状态：`src/command/gc.rs` 源文件存在，但 `src/` 树中没有任何 `mod gc` 声明（`src/command/mod.rs` 未声明该模块），因此该文件尚未被编译进二进制。
-- 用户文档：`docs/commands/gc.md`，当前仅作为 unpublished historical design 页面保留，不声明可执行 CLI 合约；已发布维护入口是 `libra maintenance run --dry-run --task gc`。
+- 公开状态：已公开；模块状态：`src/command/gc.rs` 由 `src/command/mod.rs` 导出，并通过 `src/cli.rs::Commands::Gc` 分发。
+- 用户文档：`docs/commands/gc.md`；维护入口 `libra maintenance run --dry-run --task gc` 仍可用。
 - Synopsis：`libra gc [--dry-run] [--prune=<date> | --no-prune] [--aggressive] [--auto] [--force]`。
 - 公开参数/子命令以用户文档和 CLI help 为准；当前未抽取到独立 Options/Subcommands 小节。
 
@@ -56,8 +56,7 @@ flowchart TD
 
 | 类别 | 未完成项 | 当前处理 |
 |---|---|---|
-| 兼容矩阵 | `COMPATIBILITY.md` 尚未登记该命令行。 | 需要决定是否纳入用户可见兼容矩阵和矩阵守卫。 |
-| CLI 接入 | `src/cli.rs::Commands` 尚未公开该顶层命令。 | 需要决定接入 CLI、降级为内部设计资料，或移出用户命令文档。 |
+| 打包能力 | 尚不 repack、delta-compress、创建 cruft pack 或重写有效 pack。 | 作为兼容矩阵中的 partial 缺口保留。 |
 | 功能缺口 | 当 reachability 遍历不完整时跳过 loose-object 清理（warning：`reachability traversal was incomplete; loose-object pruning was skipped`）。 | 这是保守的安全行为而非缺陷；原因写入 `warnings[]`，后续如需更完整遍历再同步源码、测试和兼容矩阵。 |
 | 兼容差异项 | 重打包有效对象 | 原始对照：不支持；相关参数/替代：支持；当前说明：不适用。 后续实现时需要补对应回归测试并同步兼容矩阵。 |
 | 兼容差异项 | cruft packs | 原始对照：不支持；相关参数/替代：支持；当前说明：不适用。 后续实现时需要补对应回归测试并同步兼容矩阵。 |
diff --git a/docs/development/internal/prune.md b/docs/development/internal/prune.md
index 0daee8538..d38133a56 100644
--- a/docs/development/internal/prune.md
+++ b/docs/development/internal/prune.md
@@ -1,23 +1,23 @@
-# `libra prune` 内部设计资料
+# `libra prune` 设计资料
 
-> Status: **declined / historical**. This command was not published to the public CLI.
+> Status: **public / partial**. `libra prune` is registered in the public CLI.
 
-This document preserves the original design notes for the unpublished `prune` implementation. It is not a user-visible command contract and is not tracked in `COMPATIBILITY.md`.
+This document preserves implementation design notes for `prune`. The user-visible command contract is tracked in [`docs/commands/prune.md`](../../commands/prune.md) and [`COMPATIBILITY.md`](../../../COMPATIBILITY.md).
 
 ## 命令实现目标
 
-`libra prune` 的目标是清理不可达对象或生成安全预览，服务于仓库维护和对象存储收敛。当前实现资料存在但顶层 CLI 尚未公开接入，后续需要决定它作为独立命令还是维护子任务公开。
+`libra prune` 的目标是清理不可达对象或生成安全预览，服务于仓库维护和对象存储收敛。当前顶层 CLI 已公开接入；日常维护仍建议优先使用 `libra gc`。
 
 ## 对比 Git 与兼容性
 
-- 兼容级别：`unpublished`。未进入 COMPATIBILITY.md；以代码接入状态为准。
+- 兼容级别：`partial`。以 `COMPATIBILITY.md` 与用户命令文档为准。
 
-- 该资料未对应公开 CLI 命令；用户可见状态按未发布处理。
+- 该资料对应公开 CLI 命令；本文只保留实现设计和维护背景。
 
 
 ## 设计方案
 
-- 入口与分发：源码资料存在但尚未公开接入 `src/cli.rs::Commands`；当前未由 `src/command/mod.rs` 导出。CLI 层在 `src/cli.rs` 把解析后的参数交给命令模块，命令模块负责把领域错误转换为 `CliError` / `CliResult`。
+- 入口与分发：`src/cli.rs::Commands::Prune` 公开接入顶层命令，`src/command/mod.rs` 导出 `prune` 模块。CLI 层在 `src/cli.rs` 把解析后的参数交给命令模块，命令模块负责把领域错误转换为 `CliError` / `CliResult`。
 - 源码分层：主要实现文件为 `src/command/prune.rs`。参数/子命令类型包括：`PruneArgs`；输出、错误或状态类型包括：`PruneOutput`、`PruneObjectInfo`（`--json` 序列化的独立输出类型，模块私有），错误通过 `CliError` / `CliResult` 传播；主要执行函数包括：`execute`、`execute_safe`。
 - 执行路径：`execute_safe` 负责 CLI 安全包装、错误映射和输出配置；索引路径会加载、比较、刷新或保存 `.libra/index`；对象路径会解析 revision 并读写 blob/tree/commit/tag 等对象；引用路径会读取或更新 SQLite refs、HEAD 与 reflog；网络路径会解析 remote 配置、协商协议并处理 pack/idx 数据；数据库路径会通过 SeaORM/SQLite 或 D1 客户端持久化元数据。
 
@@ -41,12 +41,12 @@ flowchart TD
 
 - 本节依据本地 main 分支提交历史重写，筛选与该命令实现、测试或文档路径直接相关的提交；以下是归纳后的实现脉络。
 - 2026-06-10 `75482996`（`feat(prune): implement prune command (#381)`）：基础实现节点：implement prune command (#381)；当前实现的主要轮廓可追溯到该提交。
-- 历史结论：`src/command/prune.rs` 或配套测试/文档已有历史节点，但当前 `src/cli.rs::Commands` 未公开 `prune` 入口；实现历史不改变当前状态章节中的未接入结论。
+- 历史结论：`src/command/prune.rs` 或配套测试/文档已有历史节点，当前 `src/cli.rs::Commands` 已公开 `prune` 入口。
 
 ## 当前状态
 
-- 公开状态：未公开；模块状态：未从 `src/command/mod.rs` 导出。
-- 用户文档：`docs/commands/prune.md`，当前仅作为 unpublished historical design 页面保留，不声明可执行 CLI 合约。
+- 公开状态：已公开；模块状态：`src/command/prune.rs` 由 `src/command/mod.rs` 导出，并通过 `src/cli.rs::Commands::Prune` 分发。
+- 用户文档：`docs/commands/prune.md`。
 - Synopsis：`libra prune [OPTIONS] [HEAD]...`。
 - 公开参数/子命令包括：`-n, --dry-run`、`-v, --verbose`、`--expire <TIME>`、`[HEAD]...`。
 
@@ -55,8 +55,7 @@ flowchart TD
 
 | 类别 | 未完成项 | 当前处理 |
 |---|---|---|
-| 兼容矩阵 | `COMPATIBILITY.md` 尚未登记该命令行。 | 需要决定是否纳入用户可见兼容矩阵和矩阵守卫。 |
-| CLI 接入 | `src/cli.rs::Commands` 尚未公开该顶层命令。 | 需要决定接入 CLI、降级为内部设计资料，或移出用户命令文档。 |
+| 并发写入保护 | 直接 prune 仍保留 Git-like 并发 writer 风险。 | 用户文档提示优先 dry-run 与 `--expire`，日常维护优先 `libra gc`。 |
 
 ## 维护要求
 
diff --git a/src/cli.rs b/src/cli.rs
index 93e600c86..0fae2a883 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -412,6 +412,10 @@ enum Commands {
     Pull(command::pull::PullArgs),
     #[command(about = "Verify the integrity of objects, refs, and index")]
     Fsck(command::fsck::FsckArgs),
+    #[command(about = "Prune unreachable loose objects and clean stale pack sidecars")]
+    Gc(command::gc::GcArgs),
+    #[command(about = "Prune unreachable loose objects")]
+    Prune(command::prune::PruneArgs),
     #[command(
         about = "Run tasks to optimize Git repository data",
         after_help = command::maintenance::MAINTENANCE_EXAMPLES
@@ -1260,6 +1264,8 @@ pub async fn parse_async(args: Option<&[&str]>) -> CliResult<()> {
         Commands::IndexPack(cmd_args) => command::index_pack::execute_safe(cmd_args, &output)?,
         Commands::Fetch(cmd_args) => command::fetch::execute_safe(cmd_args, &output).await?,
         Commands::Fsck(cmd_args) => command::fsck::execute_safe(cmd_args, &output).await?,
+        Commands::Gc(cmd_args) => command::gc::execute_safe(cmd_args, &output).await?,
+        Commands::Prune(cmd_args) => command::prune::execute_safe(cmd_args, &output).await?,
         Commands::Maintenance(cmd_args) => {
             command::maintenance::execute_safe(cmd_args, &output).await?
         }
diff --git a/src/command/agent/clean.rs b/src/command/agent/clean.rs
index 559a09cc7..c9f410fac 100644
--- a/src/command/agent/clean.rs
+++ b/src/command/agent/clean.rs
@@ -18,9 +18,7 @@ use serde::Serialize;
 
 use super::CleanArgs;
 use crate::{
-    internal::{
-        ai::history::HistoryManager, branch::TRACES_BRANCH, db::get_db_conn_instance,
-    },
+    internal::{ai::history::HistoryManager, branch::TRACES_BRANCH, db::get_db_conn_instance},
     utils::{
         client_storage::ClientStorage,
         error::{CliError, CliResult},
@@ -68,12 +66,8 @@ pub async fn execute_safe(args: CleanArgs, output: &OutputConfig) -> CliResult<(
     let repo_path = util::try_get_storage_path(None)
         .map_err(|e| CliError::fatal(format!("failed to locate .libra directory: {e}")))?;
     let storage = Arc::new(ClientStorage::init(repo_path.join("objects")));
-    let history = HistoryManager::new_with_ref(
-        storage,
-        repo_path,
-        Arc::new(conn.clone()),
-        TRACES_BRANCH,
-    );
+    let history =
+        HistoryManager::new_with_ref(storage, repo_path, Arc::new(conn.clone()), TRACES_BRANCH);
     let prune = history
         .prune_checkpoint_commits(&checkpoint_ids)
         .await
diff --git a/src/command/gc.rs b/src/command/gc.rs
index 1002396a8..ed49b8b14 100644
--- a/src/command/gc.rs
+++ b/src/command/gc.rs
@@ -344,7 +344,11 @@ async fn run_gc(args: &GcArgs) -> CliResult<GcOutput> {
     let policy = prune_policy(args)?;
     let objects_dir = path::objects();
     ensure_real_object_directory(&objects_dir)?;
-    let storage = ClientStorage::local(objects_dir);
+    let storage = if args.dry_run {
+        ClientStorage::init_local(objects_dir)
+    } else {
+        ClientStorage::init(objects_dir)
+    };
     let (reflogs, reflog_warnings) = expire_reflogs_for_gc(&storage, args.dry_run).await?;
     let mut reachability = collect_reachability(&storage).await?;
     reachability.warnings.extend(reflog_warnings);
@@ -1257,7 +1261,8 @@ fn is_hex_prefix(prefix: &str) -> bool {
 }
 
 /// Load root object IDs and non-reachability prune protections.
-async fn collect_roots_from_database() -> CliResult<(HashSet<ObjectHash>, HashSet<ObjectHash>)> {
+pub(crate) async fn collect_roots_from_database()
+-> CliResult<(HashSet<ObjectHash>, HashSet<ObjectHash>)> {
     ensure_regular_repository_database()?;
     let db = get_db_conn_instance().await;
     let mut roots = HashSet::new();
@@ -2005,7 +2010,7 @@ fn load_object_for_gc<T>(hash: &ObjectHash) -> Result<T, GitError>
 where
     T: ObjectTrait,
 {
-    let storage = ClientStorage::local(path::objects());
+    let storage = ClientStorage::init(path::objects());
     load_object_from_storage(&storage, hash)
 }
 
@@ -2050,7 +2055,7 @@ async fn prune_unreachable_loose_objects(
             } else {
                 remove_file(&loose.path)?;
                 remove_empty_parent_dir(&loose.path)?;
-                if !storage.local_exist(&loose.hash) {
+                if !storage.exist_local(&loose.hash) {
                     remove_object_index_rows(&loose.hash).await?;
                 }
                 GcAction::Pruned
@@ -2075,7 +2080,7 @@ async fn prune_unreachable_loose_objects(
 }
 
 /// Remove local cloud-backup index rows for an object no longer present locally.
-async fn remove_object_index_rows(hash: &ObjectHash) -> CliResult<()> {
+pub(crate) async fn remove_object_index_rows(hash: &ObjectHash) -> CliResult<()> {
     ensure_regular_repository_database()?;
     let db = get_db_conn_instance().await;
     let repo_id = current_repo_id(&db).await?;
@@ -2451,7 +2456,7 @@ mod tests {
     where
         T: ObjectTrait,
     {
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         save_object_to_storage(&storage, object, obj_id)
     }
 
@@ -2667,7 +2672,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
 
         let blob = Blob::from_content("content");
         save_test_object(&blob, &blob.id).unwrap();
@@ -2704,7 +2709,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
 
         let blob = Blob::from_content("content");
         save_test_object(&blob, &blob.id).unwrap();
@@ -2748,7 +2753,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
 
         let blob = Blob::from_content("content");
         save_test_object(&blob, &blob.id).unwrap();
@@ -2771,7 +2776,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         let missing = test_hash(12);
         let mut reachability = Reachability {
             loose: Vec::new(),
@@ -2794,7 +2799,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
 
         let blob = Blob::from_content("keep when graph is incomplete");
         save_test_object(&blob, &blob.id).unwrap();
@@ -2836,7 +2841,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
 
         let blob = Blob::from_content("garbage");
         save_test_object(&blob, &blob.id).unwrap();
@@ -2867,7 +2872,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
 
         let blob = Blob::from_content("garbage");
         save_test_object(&blob, &blob.id).unwrap();
@@ -2898,7 +2903,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
 
         let blob = Blob::from_content("indexed garbage");
         ConfigKv::set("libra.repoid", "repo-a", false)
@@ -2970,7 +2975,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
 
         let blob = Blob::from_content("cloud pending");
         save_test_object(&blob, &blob.id).unwrap();
@@ -3003,7 +3008,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
 
         let blob = Blob::from_content("reachable");
         save_test_object(&blob, &blob.id).unwrap();
@@ -3034,7 +3039,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         let pack_dir = path::objects().join("pack");
         fs::create_dir_all(&pack_dir).unwrap();
         let idx = pack_dir.join("pack-deadbeef.idx");
@@ -3059,7 +3064,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         let pack_dir = path::objects().join("pack");
         fs::create_dir_all(&pack_dir).unwrap();
         let idx = pack_dir.join("pack-deadbeef.idx");
@@ -3083,7 +3088,7 @@ mod tests {
     /// Covers pack cleanup when the pack directory is missing.
     async fn clean_pack_directory_returns_empty_when_directory_missing() {
         let dir = tempdir().unwrap();
-        let storage = ClientStorage::local(dir.path().join("objects"));
+        let storage = ClientStorage::init(dir.path().join("objects"));
 
         let stats = clean_pack_directory(&storage, PrunePolicy::Never, false).unwrap();
 
@@ -3098,7 +3103,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         let pack_dir = path::objects().join("pack");
         fs::create_dir_all(&pack_dir).unwrap();
         let pack = pack_dir.join("pack-deadbeef.pack");
@@ -3146,7 +3151,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         let pack_dir = path::objects().join("pack");
         fs::create_dir_all(&pack_dir).unwrap();
         let pack = pack_dir.join("pack-deadbeef.pack");
@@ -3177,7 +3182,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         let pack_dir = path::objects().join("pack");
         fs::create_dir_all(&pack_dir).unwrap();
         let bad_pack = pack_dir.join("pack-bad.pack");
@@ -3220,7 +3225,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         let external = tempdir().unwrap();
         let external_file = external.path().join("pack-deadbeef.idx");
         fs::write(&external_file, b"idx").unwrap();
@@ -3258,7 +3263,7 @@ mod tests {
         let objects = path::objects();
         fs::remove_dir_all(&objects).unwrap();
         symlink(external.path(), &objects).unwrap();
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
 
         let stats = clean_pack_directory(
             &storage,
@@ -3282,7 +3287,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         let pack_dir = path::objects().join("pack");
         fs::create_dir_all(&pack_dir).unwrap();
         let external = tempdir().unwrap();
@@ -3332,7 +3337,7 @@ mod tests {
         .await
         .unwrap();
 
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         let (stats, warnings) = expire_reflogs_for_gc(&storage, false).await.unwrap();
         let remaining = reflog::Entity::find().all(&db).await.unwrap();
 
@@ -3374,7 +3379,7 @@ mod tests {
         .await
         .unwrap();
 
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         let (stats, warnings) = expire_reflogs_for_gc(&storage, true).await.unwrap();
         let remaining = reflog::Entity::find().all(&db).await.unwrap();
 
@@ -3434,7 +3439,7 @@ mod tests {
             .unwrap();
         }
 
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         let (stats, warnings) = expire_reflogs_for_gc(&storage, false).await.unwrap();
         let remaining = reflog::Entity::find().all(&db).await.unwrap();
 
@@ -3480,7 +3485,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
 
         let blob = Blob::from_content("unreachable");
         save_test_object(&blob, &blob.id).unwrap();
@@ -4177,7 +4182,15 @@ mod tests {
         util::working_dir();
         let add = crate::command::add::AddArgs {
             pathspec: vec!["file.txt".into()],
-            ..Default::default()
+            all: false,
+            update: false,
+            refresh: false,
+            verbose: false,
+            force: false,
+            dry_run: false,
+            ignore_errors: false,
+            pathspec_from_file: None,
+            pathspec_file_nul: false,
         };
         crate::command::add::execute_safe(add, &OutputConfig::default())
             .await
@@ -5001,7 +5014,7 @@ mod tests {
         let repo = tempdir().unwrap();
         test::setup_with_new_libra_in(repo.path()).await;
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         let blob = Blob::from_content("stashed");
         save_test_object(&blob, &blob.id).unwrap();
         let stash_ref = util::storage_path().join("refs/stash");
@@ -5279,7 +5292,7 @@ mod tests {
         let runtime = tokio::runtime::Runtime::new().unwrap();
         runtime.block_on(test::setup_with_new_libra_in(repo.path()));
         let _guard = test::ChangeDirGuard::new(repo.path());
-        let storage = ClientStorage::local(path::objects());
+        let storage = ClientStorage::init(path::objects());
         let blob = Blob::from_content("blob");
         save_test_object(&blob, &blob.id).unwrap();
         assert!(object_children(&storage, &blob.id).unwrap().is_empty());
diff --git a/src/command/mod.rs b/src/command/mod.rs
index a1e5538f2..c332c915c 100644
--- a/src/command/mod.rs
+++ b/src/command/mod.rs
@@ -33,6 +33,7 @@ pub mod fetch;
 pub mod for_each_ref;
 pub mod format_patch;
 pub mod fsck;
+pub mod gc;
 pub mod graph;
 pub mod grep;
 pub mod hash_object;
@@ -55,6 +56,7 @@ pub mod notes;
 pub mod op;
 pub mod open;
 pub mod package;
+pub mod prune;
 pub mod publish;
 pub mod pull;
 pub mod push;
diff --git a/src/command/prune.rs b/src/command/prune.rs
index e1810babe..474650ba4 100644
--- a/src/command/prune.rs
+++ b/src/command/prune.rs
@@ -27,7 +27,7 @@ use sea_orm::{ColumnTrait, EntityTrait, QueryFilter};
 use serde::Serialize;
 
 use crate::{
-    command::load_object,
+    command::{gc, load_object, verify_pack},
     internal::{
         db,
         head::Head,
@@ -145,14 +145,20 @@ pub async fn execute_safe(args: PruneArgs, output: &OutputConfig) -> CliResult<(
     let storage = ClientStorage::init(path::objects());
     let expire_before = parse_expire_cutoff(args.expire.as_deref())?;
 
-    let reachable = collect_reachable_objects(&storage, &args.heads).await?;
+    let (reachable, protected) = collect_reachable_objects(&storage, &args.heads).await?;
     let packed = collect_packed_objects(&storage).await?;
     let needs_mtime = matches!(expire_before, PrunePolicy::ExpiredBy(_));
     let loose_objects = list_loose_objects(&storage, needs_mtime)?;
-    let plan = build_prune_plan(loose_objects, &reachable, &packed, expire_before);
+    let plan = build_prune_plan(
+        loose_objects,
+        &reachable,
+        &packed,
+        &protected,
+        expire_before,
+    );
 
     let should_report = (args.verbose || args.dry_run) && (!output.is_json() && !output.quiet);
-    apply_prune_plan(&plan, &storage, args.dry_run, should_report)?;
+    apply_prune_plan(&plan, &storage, args.dry_run, should_report).await?;
 
     if output.is_json() {
         let prune_output = PruneOutput {
@@ -225,9 +231,12 @@ fn system_time_from_unix_seconds(seconds: i64) -> SystemTime {
 async fn collect_reachable_objects(
     storage: &ClientStorage,
     heads: &[String],
-) -> CliResult<HashSet<ObjectHash>> {
-    let starting_points = collect_starting_points(storage, heads).await?;
-    bfs_mark_reachable(&starting_points, storage)
+) -> CliResult<(HashSet<ObjectHash>, HashSet<ObjectHash>)> {
+    let mut starting_points = collect_starting_points(storage, heads).await?;
+    let (gc_roots, protected) = gc::collect_roots_from_database().await?;
+    starting_points.extend(gc_roots);
+    let reachable = bfs_mark_reachable(&starting_points, storage)?;
+    Ok((reachable, protected))
 }
 
 /// Collect objects already in packfiles.
@@ -245,6 +254,10 @@ async fn collect_packed_objects(storage: &ClientStorage) -> CliResult<HashSet<Ob
         for entry in entries.flatten() {
             let path = entry.path();
             if path.extension().is_some_and(|ext| ext == "idx") {
+                let pack_path = path.with_extension("pack");
+                if verify_pack::inspect_pack_files(&path, &pack_path).is_err() {
+                    continue;
+                }
                 let packed = list_idx_objects(&path).map_err(|error| {
                     CliError::fatal(format!(
                         "failed to read pack index '{}': {error}",
@@ -475,12 +488,14 @@ fn build_prune_plan(
     loose_objects: Vec<LooseObjectInfo>,
     reachable: &HashSet<ObjectHash>,
     packed: &HashSet<ObjectHash>,
+    protected: &HashSet<ObjectHash>,
     expire_before: PrunePolicy,
 ) -> PrunePlan {
     let prunable = loose_objects
         .into_iter()
         .filter(|info| {
             (reachable.contains(&info.hash) == packed.contains(&info.hash))
+                && !protected.contains(&info.hash)
                 && is_expired(info.modified, expire_before)
         })
         .collect();
@@ -489,7 +504,7 @@ fn build_prune_plan(
 }
 
 /// Apply the prune plan by removing loose objects (or reporting in dry-run mode).
-fn apply_prune_plan(
+async fn apply_prune_plan(
     plan: &PrunePlan,
     storage: &ClientStorage,
     dry_run: bool,
@@ -509,6 +524,9 @@ fn apply_prune_plan(
         }
 
         remove_loose_object(info, objects_dir)?;
+        if !storage.exist_local(&info.hash) {
+            gc::remove_object_index_rows(&info.hash).await?;
+        }
     }
 
     Ok(())
diff --git a/src/command/verify_pack.rs b/src/command/verify_pack.rs
index b4b993751..5a0ccc94f 100644
--- a/src/command/verify_pack.rs
+++ b/src/command/verify_pack.rs
@@ -134,6 +134,18 @@ fn verify_pack(args: &VerifyPackArgs, idx_file: &Path) -> CliResult<VerifyPackOu
     })
 }
 
+pub(crate) fn inspect_pack_files(idx_file: &Path, pack_file: &Path) -> CliResult<VerifyPackOutput> {
+    verify_pack(
+        &VerifyPackArgs {
+            idx_files: vec![idx_file.to_path_buf()],
+            pack: Some(pack_file.to_path_buf()),
+            verbose: false,
+            stat_only: false,
+        },
+        idx_file,
+    )
+}
+
 const fn render_mode(args: &VerifyPackArgs) -> VerifyPackRenderMode {
     if args.stat_only {
         VerifyPackRenderMode::StatOnly
diff --git a/src/internal/ai/context_budget/compaction_agent.rs b/src/internal/ai/context_budget/compaction_agent.rs
index 14fbf2bb8..31833b4d5 100644
--- a/src/internal/ai/context_budget/compaction_agent.rs
+++ b/src/internal/ai/context_budget/compaction_agent.rs
@@ -70,7 +70,8 @@ pub const COMPACTION_AGENT_NAME: &str = "compaction";
 /// cleanly through the profile parser; production code should prefer
 /// [`embedded_compaction_system_prompt`] which extracts only the
 /// system prompt body.
-pub const EMBEDDED_COMPACTION_PROFILE: &str = include_str!("../ai/profile/embedded/compaction.md");
+pub const EMBEDDED_COMPACTION_PROFILE: &str =
+    include_str!("../agent/profile/embedded/compaction.md");
 
 /// Extract the system-prompt body from
 /// [`EMBEDDED_COMPACTION_PROFILE`] at runtime — the markdown still
diff --git a/src/utils/client_storage.rs b/src/utils/client_storage.rs
index f659d7616..5ad17d21c 100644
--- a/src/utils/client_storage.rs
+++ b/src/utils/client_storage.rs
@@ -173,6 +173,16 @@ impl ClientStorage {
         ClientStorage { storage, base_path }
     }
 
+    /// Construct a local-only `ClientStorage` rooted at `base_path`.
+    ///
+    /// This bypasses remote/tiered storage configuration entirely. Use it for
+    /// read-only scans that must not promote remote objects into the local object
+    /// directory, such as `gc --dry-run`.
+    pub fn init_local(base_path: PathBuf) -> ClientStorage {
+        let storage = Arc::new(LocalStorage::new(base_path.clone()));
+        ClientStorage { storage, base_path }
+    }
+
     /// Create a storage backend.
     ///
     /// # Remote Storage
@@ -570,6 +580,18 @@ impl ClientStorage {
         self.block_on_storage(async move { storage.exist(&hash).await })
     }
 
+    /// Check whether an object exists in the local object store only.
+    ///
+    /// This ignores any configured remote tier, but still checks local loose
+    /// objects and local packfiles. Callers that are cleaning local metadata
+    /// should use this instead of [`Self::exist`] so remote backup presence does
+    /// not make a deleted local object look locally indexed.
+    pub fn exist_local(&self, obj_id: &ObjectHash) -> bool {
+        let local = LocalStorage::new(self.base_path.clone());
+        let hash = *obj_id;
+        self.block_on_storage(async move { local.exist(&hash).await })
+    }
+
     /// Read just the `ObjectType` for `obj_id`.
     ///
     /// Boundary conditions:
diff --git a/tests/command/agent_push_test.rs b/tests/command/agent_push_test.rs
index 280ba9a20..2f094082a 100644
--- a/tests/command/agent_push_test.rs
+++ b/tests/command/agent_push_test.rs
@@ -13,7 +13,7 @@ use std::{
 
 #[cfg(unix)]
 use libra::{
-    internal::branch::{TRACES_BRANCH, Branch as InternalBranch},
+    internal::branch::{Branch as InternalBranch, TRACES_BRANCH},
     utils::test::ChangeDirGuard,
 };
 #[cfg(unix)]
@@ -131,11 +131,7 @@ fn init_repo_with_agent_traces_tip(local_dir: &Path) -> String {
     let _guard = ChangeDirGuard::new(local_dir);
     let runtime = tokio::runtime::Runtime::new().expect("failed to create tokio runtime");
     runtime
-        .block_on(InternalBranch::update_branch(
-            TRACES_BRANCH,
-            &head,
-            None,
-        ))
+        .block_on(InternalBranch::update_branch(TRACES_BRANCH, &head, None))
         .expect("failed to point traces branch at HEAD");
 
     head
diff --git a/tests/command/mod.rs b/tests/command/mod.rs
index 6d5ea796d..fdffb917e 100644
--- a/tests/command/mod.rs
+++ b/tests/command/mod.rs
@@ -300,6 +300,7 @@ mod fetch_test;
 mod for_each_ref_test;
 mod format_patch_test;
 mod fsck_test;
+mod gc_test;
 mod graph_test;
 mod grep_test;
 mod hash_object_test;
@@ -325,6 +326,7 @@ mod notes_test;
 mod op_test;
 mod open_test;
 mod output_flags_test;
+mod prune_test;
 mod publish_test;
 mod pull_json_test;
 mod pull_test;
diff --git a/tests/command/prune_test.rs b/tests/command/prune_test.rs
index 228931ee8..f758cf403 100644
--- a/tests/command/prune_test.rs
+++ b/tests/command/prune_test.rs
@@ -18,7 +18,7 @@ use git_internal::{
         types::ObjectType,
     },
 };
-use sea_orm::{ActiveModelTrait, Set};
+use sea_orm::{ActiveModelTrait, ColumnTrait, EntityTrait, QueryFilter, Set};
 use serial_test::serial;
 use tempfile::tempdir;
 
@@ -50,6 +50,57 @@ fn create_unreachable_blob(repo: &Path, content: &str) -> ObjectHash {
     blob.id
 }
 
+/// Resolve the repository id stored in local config.
+fn repo_id(repo: &Path) -> String {
+    let output = run_libra_command(&["config", "--get", "libra.repoid"], repo);
+    assert_cli_success(&output, "failed to read libra.repoid");
+    String::from_utf8_lossy(&output.stdout).trim().to_string()
+}
+
+/// Enable the repository cloud-backup config path used by prune protections.
+fn enable_cloud_backup(repo: &Path) {
+    let output = run_libra_command(
+        &["config", "set", "vault.env.LIBRA_STORAGE_TYPE", "r2"],
+        repo,
+    );
+    assert_cli_success(&output, "failed to set cloud storage type");
+}
+
+/// Insert an object_index row for the provided object.
+fn insert_object_index_row(repo: &Path, hash: &ObjectHash, repo_id: &str, is_synced: i32) {
+    let _guard = ChangeDirGuard::new(repo);
+    let runtime = tokio::runtime::Runtime::new().expect("runtime");
+    runtime.block_on(async {
+        let db_conn = libra::internal::db::get_db_conn_instance().await;
+        let model = libra::internal::model::object_index::ActiveModel {
+            o_id: Set(hash.to_string()),
+            o_type: Set("blob".to_string()),
+            o_size: Set(1),
+            repo_id: Set(repo_id.to_string()),
+            created_at: Set(1),
+            is_synced: Set(is_synced),
+            ..Default::default()
+        };
+        model.insert(&db_conn).await.expect("insert object_index");
+    });
+}
+
+/// Return whether an object_index row exists for the provided object and repo.
+fn object_index_row_exists(repo: &Path, hash: &ObjectHash, repo_id: &str) -> bool {
+    let _guard = ChangeDirGuard::new(repo);
+    let runtime = tokio::runtime::Runtime::new().expect("runtime");
+    runtime.block_on(async {
+        let db_conn = libra::internal::db::get_db_conn_instance().await;
+        libra::internal::model::object_index::Entity::find()
+            .filter(libra::internal::model::object_index::Column::OId.eq(hash.to_string()))
+            .filter(libra::internal::model::object_index::Column::RepoId.eq(repo_id))
+            .one(&db_conn)
+            .await
+            .expect("query object_index")
+            .is_some()
+    })
+}
+
 /// Create an unreachable commit (and its tree/blob) stored as loose objects.
 fn create_unreachable_commit(repo: &Path, label: &str) -> (ObjectHash, ObjectHash, ObjectHash) {
     let _guard = ChangeDirGuard::new(repo);
@@ -135,6 +186,16 @@ fn insert_reflog_entry(repo: &Path, new_oid: &ObjectHash) {
     });
 }
 
+/// Write merge recovery metadata that references the provided object.
+fn write_merge_state(repo: &Path, target: &ObjectHash) {
+    let state_path = repo.join(".libra").join("merge-state.json");
+    fs::write(
+        state_path,
+        format!(r#"{{"orig_head":null,"target":"{target}","base":null}}"#),
+    )
+    .expect("write merge-state.json");
+}
+
 /// Insert an invalid reference row to exercise parse errors in prune.
 fn insert_invalid_reference(repo: &Path, name: &str, commit: &str) {
     let _guard = ChangeDirGuard::new(repo);
@@ -233,6 +294,47 @@ fn test_prune_removes_unreachable_blob() {
     assert!(!blob_path.exists());
 }
 
+#[test]
+#[serial]
+/// Tests direct prune preserves cloud-pending objects until backup sync completes.
+fn test_prune_keeps_unsynced_cloud_backup_object() {
+    let repo = create_committed_repo_via_cli();
+    enable_cloud_backup(repo.path());
+    let repo_id = repo_id(repo.path());
+    let blob = create_unreachable_blob(repo.path(), "cloud-pending");
+    let blob_path = loose_object_path(repo.path(), &blob.to_string());
+    insert_object_index_row(repo.path(), &blob, &repo_id, 0);
+
+    let output = run_libra_command(&["prune"], repo.path());
+    assert_cli_success(&output, "prune should succeed");
+
+    assert!(
+        blob_path.exists(),
+        "unsynced object_index rows should protect loose objects from prune"
+    );
+}
+
+#[test]
+#[serial]
+/// Tests direct prune removes local object_index rows after deleting synced garbage.
+fn test_prune_removes_synced_object_index_row() {
+    let repo = create_committed_repo_via_cli();
+    let repo_id = repo_id(repo.path());
+    let blob = create_unreachable_blob(repo.path(), "synced-garbage");
+    let blob_path = loose_object_path(repo.path(), &blob.to_string());
+    insert_object_index_row(repo.path(), &blob, &repo_id, 1);
+    assert!(object_index_row_exists(repo.path(), &blob, &repo_id));
+
+    let output = run_libra_command(&["prune"], repo.path());
+    assert_cli_success(&output, "prune should succeed");
+
+    assert!(!blob_path.exists());
+    assert!(
+        !object_index_row_exists(repo.path(), &blob, &repo_id),
+        "synced object_index row should be removed after local prune"
+    );
+}
+
 #[test]
 #[serial]
 /// Tests --dry-run reports prunable objects without deleting them.
@@ -386,6 +488,22 @@ fn test_prune_keeps_reflog_reachable_commit() {
     assert!(object_exists(repo.path(), &commit.to_string()));
 }
 
+#[test]
+#[serial]
+/// Tests merge-state roots are preserved by direct prune.
+fn test_prune_keeps_merge_state_commit() {
+    let repo = create_committed_repo_via_cli();
+    let (commit, tree, blob) = create_unreachable_commit(repo.path(), "merge-state-commit");
+    write_merge_state(repo.path(), &commit);
+
+    let output = run_libra_command(&["prune"], repo.path());
+    assert_cli_success(&output, "prune should preserve merge-state roots");
+
+    assert!(object_exists(repo.path(), &commit.to_string()));
+    assert!(object_exists(repo.path(), &tree.to_string()));
+    assert!(object_exists(repo.path(), &blob.to_string()));
+}
+
 #[test]
 #[serial]
 /// Tests multiple head arguments keep their objects reachable.
@@ -417,8 +535,8 @@ fn test_prune_head_arg_tag_is_accepted() {
 
 #[test]
 #[serial]
-/// Tests packed v2 indexes trigger pruning of loose duplicates.
-fn test_prune_packed_v2_prunes_reachable_duplicate() {
+/// Tests orphan v2 pack indexes do not trigger pruning of reachable loose copies.
+fn test_prune_orphan_packed_v2_keeps_reachable_duplicate() {
     let repo = create_committed_repo_via_cli();
     let head = head_commit_hash(repo.path());
     assert!(object_exists(repo.path(), &head));
@@ -430,13 +548,13 @@ fn test_prune_packed_v2_prunes_reachable_duplicate() {
 
     let output = run_libra_command(&["prune"], repo.path());
     assert_cli_success(&output, "prune should succeed");
-    assert!(!object_exists(repo.path(), &head));
+    assert!(object_exists(repo.path(), &head));
 }
 
 #[test]
 #[serial]
-/// Tests packed v1 indexes trigger pruning of loose duplicates.
-fn test_prune_packed_v1_prunes_reachable_duplicate() {
+/// Tests orphan v1 pack indexes do not trigger pruning of reachable loose copies.
+fn test_prune_orphan_packed_v1_keeps_reachable_duplicate() {
     let repo = create_committed_repo_via_cli();
     let head = head_commit_hash(repo.path());
     assert!(object_exists(repo.path(), &head));
@@ -448,7 +566,7 @@ fn test_prune_packed_v1_prunes_reachable_duplicate() {
 
     let output = run_libra_command(&["prune"], repo.path());
     assert_cli_success(&output, "prune should succeed");
-    assert!(!object_exists(repo.path(), &head));
+    assert!(object_exists(repo.path(), &head));
 }
 
 #[test]
diff --git a/tests/publish_ai_object_model_contract_test.rs b/tests/publish_ai_object_model_contract_test.rs
index c5cd69502..50ef85b26 100644
--- a/tests/publish_ai_object_model_contract_test.rs
+++ b/tests/publish_ai_object_model_contract_test.rs
@@ -12,7 +12,7 @@ fn fixture(name: &str) -> serde_json::Value {
 
 #[test]
 fn publish_ai_object_model_contract_test_fixtures_cover_reference_layers() {
-    let reference = include_str!("../docs/agent/ai-object-model-reference.md");
+    let reference = include_str!("../docs/ai/object-model-reference.md");
     let snapshot: PublishAiObject = serde_json::from_value(fixture("ai-object.json")).unwrap();
     let event: PublishAiObject = serde_json::from_value(fixture("ai-object-event.json")).unwrap();
     let projection: PublishAiObject =

From ce471c4f474a2c00d4bf5fb457b50ba73d401710 Mon Sep 17 00:00:00 2001
From: marshawcoco <marshawcoco@gmail.com>
Date: Thu, 25 Jun 2026 02:53:39 +0000
Subject: [PATCH 2/7] fix(prune): keep dry runs local-only

Signed-off-by: marshawcoco <marshawcoco@gmail.com>
---
 src/command/prune.rs | 56 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

diff --git a/src/command/prune.rs b/src/command/prune.rs
index 474650ba4..a1ca069d4 100644
--- a/src/command/prune.rs
+++ b/src/command/prune.rs
@@ -142,7 +142,13 @@ pub async fn execute(args: PruneArgs) -> Result<(), String> {
 pub async fn execute_safe(args: PruneArgs, output: &OutputConfig) -> CliResult<()> {
     util::require_repo().map_err(|_| CliError::repo_not_found())?;
 
-    let storage = ClientStorage::init(path::objects());
+    let objects_dir = path::objects();
+    let objects_dir_existed = objects_dir.exists();
+    let storage = if args.dry_run {
+        ClientStorage::init_local(objects_dir.clone())
+    } else {
+        ClientStorage::init(objects_dir.clone())
+    };
     let expire_before = parse_expire_cutoff(args.expire.as_deref())?;
 
     let (reachable, protected) = collect_reachable_objects(&storage, &args.heads).await?;
@@ -178,6 +184,28 @@ pub async fn execute_safe(args: PruneArgs, output: &OutputConfig) -> CliResult<(
         emit_json_data("prune", &prune_output, output)?;
     }
 
+    cleanup_dry_run_objects_dir(args.dry_run, objects_dir_existed, &objects_dir)?;
+
+    Ok(())
+}
+
+fn cleanup_dry_run_objects_dir(
+    dry_run: bool,
+    objects_dir_existed: bool,
+    objects_dir: &Path,
+) -> CliResult<()> {
+    if !dry_run || objects_dir_existed || !objects_dir.exists() {
+        return Ok(());
+    }
+    if is_dir_empty(objects_dir)? {
+        fs::remove_dir(objects_dir).map_err(|error| {
+            CliError::fatal(format!(
+                "failed to remove empty dry-run objects directory '{}': {error}",
+                objects_dir.display()
+            ))
+            .with_stable_code(StableErrorCode::IoWriteFailed)
+        })?;
+    }
     Ok(())
 }
 
@@ -798,6 +826,7 @@ mod tests {
     use tempfile::tempdir;
 
     use super::*;
+    use crate::utils::test;
 
     #[test]
     fn list_idx_objects_reads_v2_hashes() {
@@ -862,4 +891,29 @@ mod tests {
             "symlinked outside object should not be listed"
         );
     }
+
+    #[tokio::test]
+    #[serial_test::serial]
+    /// Covers dry-run prune inspecting a missing object directory without creating it.
+    async fn execute_safe_dry_run_does_not_create_missing_object_directory() {
+        let repo = tempdir().expect("tempdir");
+        test::setup_with_new_libra_in(repo.path()).await;
+        let _guard = test::ChangeDirGuard::new(repo.path());
+        let objects = path::objects();
+        fs::remove_dir_all(&objects).expect("remove objects directory");
+
+        execute_safe(
+            PruneArgs {
+                dry_run: true,
+                verbose: false,
+                expire: None,
+                heads: Vec::new(),
+            },
+            &OutputConfig::default(),
+        )
+        .await
+        .expect("prune dry-run should succeed");
+
+        assert!(!objects.exists());
+    }
 }

From edcb9e30efb7519553861d8cd580b53031575f87 Mon Sep 17 00:00:00 2001
From: marshawcoco <marshawcoco@gmail.com>
Date: Thu, 25 Jun 2026 03:04:16 +0000
Subject: [PATCH 3/7] fix(tag): box annotated create future

Signed-off-by: marshawcoco <marshawcoco@gmail.com>
---
 src/command/tag.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/command/tag.rs b/src/command/tag.rs
index 5e070fa7e..569eff5cf 100644
--- a/src/command/tag.rs
+++ b/src/command/tag.rs
@@ -642,7 +642,7 @@ async fn run_create_tag(
     force: bool,
     sign: bool,
 ) -> Result<TagOutput, TagError> {
-    let created = tag::create(tag_name, message, force, sign)
+    let created = Box::pin(tag::create(tag_name, message, force, sign))
         .await
         .map_err(|error| map_create_tag_error(tag_name, error))?;
     Ok(TagOutput::Create {

From 02b3888320d545282125dc1ae8df61e6f747e537 Mon Sep 17 00:00:00 2001
From: marshawcoco <marshawcoco@gmail.com>
Date: Thu, 25 Jun 2026 04:42:48 +0000
Subject: [PATCH 4/7] fix(ci): harden dry-run scans and tag tests

Signed-off-by: marshawcoco <marshawcoco@gmail.com>
---
 src/command/gc.rs           |  23 ++---
 src/command/prune.rs        |  47 +++++----
 src/command/tag.rs          | 190 +++++++++++++++++++++---------------
 src/utils/client_storage.rs |   5 +-
 src/utils/storage/local.rs  |   7 ++
 5 files changed, 159 insertions(+), 113 deletions(-)

diff --git a/src/command/gc.rs b/src/command/gc.rs
index ed49b8b14..a63c5787b 100644
--- a/src/command/gc.rs
+++ b/src/command/gc.rs
@@ -458,12 +458,14 @@ async fn expire_reflogs_for_gc(
     };
 
     for ref_name in refs {
+        let parent_storage = storage.clone();
+        let commit_storage = storage.clone();
         let result = expire_reflog(
             &db,
             &ref_name,
             &options,
-            gc_load_commit_parents,
-            gc_oid_is_commit,
+            move |oid| gc_load_commit_parents(&parent_storage, oid),
+            move |oid| gc_oid_is_commit(&commit_storage, oid),
         )
         .await
         .map_err(map_gc_reflog_error)?;
@@ -542,9 +544,9 @@ fn reflog_parent_traversal_warning(storage: &ClientStorage, tips: &[ObjectHash])
 }
 
 /// Load commit parents for reflog reachability expiration.
-fn gc_load_commit_parents(oid: &str) -> Option<Vec<String>> {
+fn gc_load_commit_parents(storage: &ClientStorage, oid: &str) -> Option<Vec<String>> {
     let hash = ObjectHash::from_str(oid).ok()?;
-    let commit: Commit = load_object_for_gc(&hash).ok()?;
+    let commit: Commit = load_object_from_storage(storage, &hash).ok()?;
     Some(
         commit
             .parent_commit_ids
@@ -555,10 +557,10 @@ fn gc_load_commit_parents(oid: &str) -> Option<Vec<String>> {
 }
 
 /// Return whether a reflog object ID still loads as a commit.
-fn gc_oid_is_commit(oid: &str) -> bool {
+fn gc_oid_is_commit(storage: &ClientStorage, oid: &str) -> bool {
     ObjectHash::from_str(oid)
         .ok()
-        .is_some_and(|hash| load_object_for_gc::<Commit>(&hash).is_ok())
+        .is_some_and(|hash| load_object_from_storage::<Commit>(storage, &hash).is_ok())
 }
 
 /// Convert reflog-expiration failures into GC CLI errors.
@@ -2005,15 +2007,6 @@ where
     T::from_bytes(&data, *hash)
 }
 
-/// Load one object through the GC-local storage backend.
-fn load_object_for_gc<T>(hash: &ObjectHash) -> Result<T, GitError>
-where
-    T: ObjectTrait,
-{
-    let storage = ClientStorage::init(path::objects());
-    load_object_from_storage(&storage, hash)
-}
-
 /// Convert an object-load failure into a repository-corruption CLI error.
 fn corrupt_object(hash: &ObjectHash, error: GitError) -> CliError {
     CliError::fatal(format!("failed to load reachable object {hash}: {error}"))
diff --git a/src/command/prune.rs b/src/command/prune.rs
index a1ca069d4..f9caec80a 100644
--- a/src/command/prune.rs
+++ b/src/command/prune.rs
@@ -144,12 +144,17 @@ pub async fn execute_safe(args: PruneArgs, output: &OutputConfig) -> CliResult<(
 
     let objects_dir = path::objects();
     let objects_dir_existed = objects_dir.exists();
+    let expire_before = parse_expire_cutoff(args.expire.as_deref())?;
+    if args.dry_run && !objects_dir_existed {
+        render_prune_json(&PrunePlan { prunable: vec![] }, &args, output)?;
+        return Ok(());
+    }
+
     let storage = if args.dry_run {
         ClientStorage::init_local(objects_dir.clone())
     } else {
         ClientStorage::init(objects_dir.clone())
     };
-    let expire_before = parse_expire_cutoff(args.expire.as_deref())?;
 
     let (reachable, protected) = collect_reachable_objects(&storage, &args.heads).await?;
     let packed = collect_packed_objects(&storage).await?;
@@ -166,29 +171,35 @@ pub async fn execute_safe(args: PruneArgs, output: &OutputConfig) -> CliResult<(
     let should_report = (args.verbose || args.dry_run) && (!output.is_json() && !output.quiet);
     apply_prune_plan(&plan, &storage, args.dry_run, should_report).await?;
 
-    if output.is_json() {
-        let prune_output = PruneOutput {
-            objects: plan
-                .prunable
-                .iter()
-                .map(|info| PruneObjectInfo {
-                    object_id: info.hash.to_string(),
-                    object_type: info.obj_type.to_string(),
-                })
-                .collect(),
-            expire: args.expire,
-            heads: args.heads,
-            dry_run: args.dry_run,
-            verbose: args.verbose,
-        };
-        emit_json_data("prune", &prune_output, output)?;
-    }
+    render_prune_json(&plan, &args, output)?;
 
     cleanup_dry_run_objects_dir(args.dry_run, objects_dir_existed, &objects_dir)?;
 
     Ok(())
 }
 
+fn render_prune_json(plan: &PrunePlan, args: &PruneArgs, output: &OutputConfig) -> CliResult<()> {
+    if !output.is_json() {
+        return Ok(());
+    }
+
+    let prune_output = PruneOutput {
+        objects: plan
+            .prunable
+            .iter()
+            .map(|info| PruneObjectInfo {
+                object_id: info.hash.to_string(),
+                object_type: info.obj_type.to_string(),
+            })
+            .collect(),
+        expire: args.expire.clone(),
+        heads: args.heads.clone(),
+        dry_run: args.dry_run,
+        verbose: args.verbose,
+    };
+    emit_json_data("prune", &prune_output, output)
+}
+
 fn cleanup_dry_run_objects_dir(
     dry_run: bool,
     objects_dir_existed: bool,
diff --git a/src/command/tag.rs b/src/command/tag.rs
index 569eff5cf..15a96fd20 100644
--- a/src/command/tag.rs
+++ b/src/command/tag.rs
@@ -444,14 +444,14 @@ fn validate_named_tag_action(args: &TagArgs) -> Result<(), TagError> {
 
 #[cfg(test)]
 async fn create_tag(tag_name: &str, message: Option<String>, force: bool) {
-    if let Err(err) = create_tag_safe(tag_name, message, force).await {
+    if let Err(err) = Box::pin(create_tag_safe(tag_name, message, force)).await {
         err.print_stderr();
     }
 }
 
 #[cfg(test)]
 async fn create_tag_safe(tag_name: &str, message: Option<String>, force: bool) -> CliResult<()> {
-    run_create_tag(tag_name, message, force, false)
+    Box::pin(run_create_tag(tag_name, message, force, false))
         .await
         .map(|_| ())
         .map_err(CliError::from)?;
@@ -680,7 +680,7 @@ async fn collect_tags(
     merged: Option<&ObjectHash>,
     no_merged: Option<&ObjectHash>,
 ) -> Result<Vec<TagListEntry>, TagError> {
-    let tags = tag::list().await.map_err(TagError::ListFailed)?;
+    let tags = Box::pin(tag::list()).await.map_err(TagError::ListFailed)?;
     let mut entries = Vec::with_capacity(tags.len());
     for tag in tags {
         // `tag -l <pattern>` keeps only tags whose name matches the fnmatch glob.
@@ -966,7 +966,7 @@ async fn resolve_tag_ref_for_delete(tag_name: &str) -> Result<tag::TagReference,
 
 #[cfg(test)]
 mod tests {
-    use std::fs;
+    use std::{fs, future::Future};
 
     use git_internal::internal::object::types::ObjectType;
     use sea_orm::DbErr;
@@ -1025,99 +1025,133 @@ mod tests {
         (temp_dir, guard)
     }
 
-    #[tokio::test]
+    fn run_async_tag_test<F, Fut>(body: F)
+    where
+        F: FnOnce() -> Fut + Send + 'static,
+        Fut: Future<Output = ()> + 'static,
+    {
+        std::thread::Builder::new()
+            .name("tag-test-runtime".to_string())
+            .stack_size(8 * 1024 * 1024)
+            .spawn(move || {
+                let runtime = tokio::runtime::Builder::new_current_thread()
+                    .enable_all()
+                    .build()
+                    .expect("failed to build tag test runtime");
+                runtime.block_on(body());
+            })
+            .expect("failed to spawn tag test thread")
+            .join()
+            .expect("tag test thread panicked");
+    }
+
+    #[test]
     #[serial]
-    async fn test_create_and_list_lightweight_tag() {
-        let (_temp_dir, _guard) = setup_repo_with_commit().await;
-        create_tag("v1.0-light", None, false).await;
-        let tags = tag::list().await.unwrap();
-        assert_eq!(tags.len(), 1);
-        assert_eq!(tags[0].name, "v1.0-light");
-        assert_eq!(tags[0].object.get_type(), ObjectType::Commit);
+    fn test_create_and_list_lightweight_tag() {
+        run_async_tag_test(|| async {
+            let (_temp_dir, _guard) = Box::pin(setup_repo_with_commit()).await;
+            create_tag("v1.0-light", None, false).await;
+            let tags = Box::pin(tag::list()).await.unwrap();
+            assert_eq!(tags.len(), 1);
+            assert_eq!(tags[0].name, "v1.0-light");
+            assert_eq!(tags[0].object.get_type(), ObjectType::Commit);
+        });
     }
 
-    #[tokio::test]
+    #[test]
     #[serial]
-    async fn test_create_and_list_lightweight_tag_force() {
-        let (_temp_dir, _guard) = setup_repo_with_commit().await;
-        create_tag("v1.0-light", None, false).await;
-        create_tag("v1.0-light", None, true).await;
-        let tags = tag::list().await.unwrap();
-        assert_eq!(tags.len(), 1);
-        assert_eq!(tags[0].name, "v1.0-light");
-        assert_eq!(tags[0].object.get_type(), ObjectType::Commit);
+    fn test_create_and_list_lightweight_tag_force() {
+        run_async_tag_test(|| async {
+            let (_temp_dir, _guard) = Box::pin(setup_repo_with_commit()).await;
+            create_tag("v1.0-light", None, false).await;
+            create_tag("v1.0-light", None, true).await;
+            let tags = Box::pin(tag::list()).await.unwrap();
+            assert_eq!(tags.len(), 1);
+            assert_eq!(tags[0].name, "v1.0-light");
+            assert_eq!(tags[0].object.get_type(), ObjectType::Commit);
+        });
     }
 
-    #[tokio::test]
+    #[test]
     #[serial]
-    async fn test_create_and_list_annotated_tag() {
-        let (_temp_dir, _guard) = setup_repo_with_commit().await;
-        create_tag("v1.0-annotated", Some("Release v1.0".to_string()), false).await;
-        let tags = tag::list().await.unwrap();
-        assert_eq!(tags.len(), 1);
-        assert_eq!(tags[0].name, "v1.0-annotated");
-        assert_eq!(tags[0].object.get_type(), ObjectType::Tag);
+    fn test_create_and_list_annotated_tag() {
+        run_async_tag_test(|| async {
+            let (_temp_dir, _guard) = Box::pin(setup_repo_with_commit()).await;
+            create_tag("v1.0-annotated", Some("Release v1.0".to_string()), false).await;
+            let tags = Box::pin(tag::list()).await.unwrap();
+            assert_eq!(tags.len(), 1);
+            assert_eq!(tags[0].name, "v1.0-annotated");
+            assert_eq!(tags[0].object.get_type(), ObjectType::Tag);
+        });
     }
 
-    #[tokio::test]
+    #[test]
     #[serial]
-    async fn test_create_and_list_annotated_tag_force() {
-        let (_temp_dir, _guard) = setup_repo_with_commit().await;
-        create_tag("v1.0-annotated", Some("Release v1.0".to_string()), false).await;
-        create_tag("v1.0-annotated", Some("Release v2.0".to_string()), true).await;
-        let tags = tag::list().await.unwrap();
-        assert_eq!(tags.len(), 1);
-        assert_eq!(tags[0].name, "v1.0-annotated");
-        assert_eq!(tags[0].object.get_type(), ObjectType::Tag);
-
-        // Check message
-        let result = tag::find_tag_and_commit("v1.0-annotated").await;
-        assert!(result.is_ok());
-        let (object, _) = result.unwrap().unwrap();
-        if let tag::TagObject::Tag(tag_object) = object {
-            assert_eq!(tag_object.message, "Release v2.0");
-        }
+    fn test_create_and_list_annotated_tag_force() {
+        run_async_tag_test(|| async {
+            let (_temp_dir, _guard) = Box::pin(setup_repo_with_commit()).await;
+            create_tag("v1.0-annotated", Some("Release v1.0".to_string()), false).await;
+            create_tag("v1.0-annotated", Some("Release v2.0".to_string()), true).await;
+            let tags = Box::pin(tag::list()).await.unwrap();
+            assert_eq!(tags.len(), 1);
+            assert_eq!(tags[0].name, "v1.0-annotated");
+            assert_eq!(tags[0].object.get_type(), ObjectType::Tag);
+
+            // Check message
+            let result = tag::find_tag_and_commit("v1.0-annotated").await;
+            assert!(result.is_ok());
+            let (object, _) = result.unwrap().unwrap();
+            if let tag::TagObject::Tag(tag_object) = object {
+                assert_eq!(tag_object.message, "Release v2.0");
+            }
+        });
     }
 
-    #[tokio::test]
+    #[test]
     #[serial]
-    async fn test_show_lightweight_tag() {
-        let (_temp_dir, _guard) = setup_repo_with_commit().await;
-        create_tag("v1.0-light", None, false).await;
-        let result = tag::find_tag_and_commit("v1.0-light").await;
-        assert!(result.is_ok());
-        let (object, commit) = result.unwrap().unwrap();
-        assert_eq!(object.get_type(), ObjectType::Commit);
-        assert_eq!(commit.message.trim(), "Initial commit");
+    fn test_show_lightweight_tag() {
+        run_async_tag_test(|| async {
+            let (_temp_dir, _guard) = Box::pin(setup_repo_with_commit()).await;
+            create_tag("v1.0-light", None, false).await;
+            let result = tag::find_tag_and_commit("v1.0-light").await;
+            assert!(result.is_ok());
+            let (object, commit) = result.unwrap().unwrap();
+            assert_eq!(object.get_type(), ObjectType::Commit);
+            assert_eq!(commit.message.trim(), "Initial commit");
+        });
     }
 
-    #[tokio::test]
+    #[test]
     #[serial]
-    async fn test_show_annotated_tag() {
-        let (_temp_dir, _guard) = setup_repo_with_commit().await;
-        create_tag("v1.0-annotated", Some("Test message".to_string()), false).await;
-        let result = tag::find_tag_and_commit("v1.0-annotated").await;
-        assert!(result.is_ok());
-        let (object, commit) = result.unwrap().unwrap();
-        assert_eq!(object.get_type(), ObjectType::Tag);
-        assert_eq!(commit.message.trim(), "Initial commit");
-
-        // Verify tag object content directly from the TagObject enum
-        if let tag::TagObject::Tag(tag_object) = object {
-            assert_eq!(tag_object.message, "Test message");
-        } else {
-            panic!("Expected Tag object type");
-        }
+    fn test_show_annotated_tag() {
+        run_async_tag_test(|| async {
+            let (_temp_dir, _guard) = Box::pin(setup_repo_with_commit()).await;
+            create_tag("v1.0-annotated", Some("Test message".to_string()), false).await;
+            let result = tag::find_tag_and_commit("v1.0-annotated").await;
+            assert!(result.is_ok());
+            let (object, commit) = result.unwrap().unwrap();
+            assert_eq!(object.get_type(), ObjectType::Tag);
+            assert_eq!(commit.message.trim(), "Initial commit");
+
+            // Verify tag object content directly from the TagObject enum
+            if let tag::TagObject::Tag(tag_object) = object {
+                assert_eq!(tag_object.message, "Test message");
+            } else {
+                panic!("Expected Tag object type");
+            }
+        });
     }
 
-    #[tokio::test]
+    #[test]
     #[serial]
-    async fn test_delete_tag() {
-        let (_temp_dir, _guard) = setup_repo_with_commit().await;
-        create_tag("v1.0", None, false).await;
-        delete_tag("v1.0").await;
-        let tags = tag::list().await.unwrap();
-        assert!(tags.is_empty());
+    fn test_delete_tag() {
+        run_async_tag_test(|| async {
+            let (_temp_dir, _guard) = Box::pin(setup_repo_with_commit()).await;
+            create_tag("v1.0", None, false).await;
+            delete_tag("v1.0").await;
+            let tags = Box::pin(tag::list()).await.unwrap();
+            assert!(tags.is_empty());
+        });
     }
 
     #[test]
diff --git a/src/utils/client_storage.rs b/src/utils/client_storage.rs
index 5ad17d21c..633dabfe7 100644
--- a/src/utils/client_storage.rs
+++ b/src/utils/client_storage.rs
@@ -177,9 +177,10 @@ impl ClientStorage {
     ///
     /// This bypasses remote/tiered storage configuration entirely. Use it for
     /// read-only scans that must not promote remote objects into the local object
-    /// directory, such as `gc --dry-run`.
+    /// directory, such as `gc --dry-run`. The local backend is non-creating so
+    /// preview scans do not create a missing `.libra/objects` directory.
     pub fn init_local(base_path: PathBuf) -> ClientStorage {
-        let storage = Arc::new(LocalStorage::new(base_path.clone()));
+        let storage = Arc::new(LocalStorage::new_without_create(base_path.clone()));
         ClientStorage { storage, base_path }
     }
 
diff --git a/src/utils/storage/local.rs b/src/utils/storage/local.rs
index 1e19a8837..aebfcf0b6 100644
--- a/src/utils/storage/local.rs
+++ b/src/utils/storage/local.rs
@@ -62,6 +62,13 @@ impl LocalStorage {
         }
     }
 
+    pub fn new_without_create(base_path: PathBuf) -> Self {
+        Self {
+            base_path,
+            hash_kind: Some(get_hash_kind()),
+        }
+    }
+
     /// Transforms an object hash into a path like "ab/cdef...". This is used for loose objects.
     fn transform_path(&self, hash: &ObjectHash) -> String {
         let hash = hash.to_string();

From ce4d2d55956c4e9bb727ab201f4b56b152c39693 Mon Sep 17 00:00:00 2001
From: marshawcoco <marshawcoco@gmail.com>
Date: Thu, 25 Jun 2026 08:01:47 +0000
Subject: [PATCH 5/7] fix(prune): guard public prune safety paths

Signed-off-by: marshawcoco <marshawcoco@gmail.com>
---
 src/cli.rs                   |  2 +-
 src/command/cat_file.rs      |  2 +-
 src/command/gc.rs            |  4 +--
 src/command/prune.rs         | 32 +++++++++++++++--
 src/internal/db/migration.rs | 27 +++++++++++++-
 tests/command/prune_test.rs  | 69 +++++++++++++++++++++++++++++++++++-
 6 files changed, 128 insertions(+), 8 deletions(-)

diff --git a/src/cli.rs b/src/cli.rs
index 0fae2a883..0fb7ebc00 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -36,7 +36,7 @@ Command Groups:
   Commit And Branching    commit, branch, switch, checkout, tag, merge, rebase, reset, cherry-pick, revert
   Remote And Cloud        remote, fetch, pull, push, open, cloud, publish
   AI And Automation       code, code-control, automation, usage, graph, sandbox, agent
-  Maintenance And Plumbing fsck, maintenance, cat-file, hash-object, verify-pack, rev-parse, rev-list, symbolic-ref, reflog, bisect, for-each-ref
+  Maintenance And Plumbing fsck, gc, prune, maintenance, cat-file, hash-object, verify-pack, rev-parse, rev-list, symbolic-ref, reflog, bisect, for-each-ref
 
 Help Topics:
   error-codes  Print the stable CLI error code table (`libra help error-codes`)
diff --git a/src/command/cat_file.rs b/src/command/cat_file.rs
index bfe8e40fb..cd148ad46 100644
--- a/src/command/cat_file.rs
+++ b/src/command/cat_file.rs
@@ -53,7 +53,7 @@ Modes:
   - AI listing modes: use --ai-list <TYPE> or --ai-list-types.
 
 Notes:
-  - OBJECT is ignored for all --ai* and --batch* modes.
+  - OBJECT is ignored for all --ai* modes and all --batch* modes.
   - --ai and --ai-type search the AI history branch and can resolve persisted session objects such as ai_session.
   - If the same ID exists under multiple AI types, pass TYPE:ID to disambiguate.
   - --ai on ai_session objects prints a unified session summary before full JSON.
diff --git a/src/command/gc.rs b/src/command/gc.rs
index a63c5787b..59d31f7e6 100644
--- a/src/command/gc.rs
+++ b/src/command/gc.rs
@@ -248,7 +248,7 @@ struct PackGroup {
 }
 
 /// Held while a `gc` process owns `.libra/gc.lock`.
-struct GcLockGuard {
+pub(crate) struct GcLockGuard {
     /// Path to the lock file that should be removed on drop.
     path: PathBuf,
     /// Random owner token written to the lock file for safe cleanup.
@@ -574,7 +574,7 @@ fn map_gc_reflog_error(error: ReflogError) -> CliError {
 }
 
 /// Acquire the repository-local GC lock.
-fn acquire_gc_lock(force: bool) -> CliResult<GcLockGuard> {
+pub(crate) fn acquire_gc_lock(force: bool) -> CliResult<GcLockGuard> {
     let path = util::storage_path().join("gc.lock");
     let token = generate_gc_lock_token()?;
     match fs::OpenOptions::new()
diff --git a/src/command/prune.rs b/src/command/prune.rs
index f9caec80a..d038ff9d8 100644
--- a/src/command/prune.rs
+++ b/src/command/prune.rs
@@ -16,7 +16,7 @@ use std::{
 use byteorder::{BigEndian, ReadBytesExt};
 use clap::Parser;
 use git_internal::{
-    hash::{ObjectHash, get_hash_kind},
+    hash::{HashKind, ObjectHash, get_hash_kind, set_hash_kind},
     internal::{
         index::Index,
         object::{commit::Commit, tag::Tag, tree::Tree, types::ObjectType},
@@ -141,6 +141,11 @@ pub async fn execute(args: PruneArgs) -> Result<(), String> {
 /// failures while scanning or deleting objects.
 pub async fn execute_safe(args: PruneArgs, output: &OutputConfig) -> CliResult<()> {
     util::require_repo().map_err(|_| CliError::repo_not_found())?;
+    let _gc_lock = if args.dry_run {
+        None
+    } else {
+        Some(gc::acquire_gc_lock(false)?)
+    };
 
     let objects_dir = path::objects();
     let objects_dir_existed = objects_dir.exists();
@@ -294,7 +299,7 @@ async fn collect_packed_objects(storage: &ClientStorage) -> CliResult<HashSet<Ob
             let path = entry.path();
             if path.extension().is_some_and(|ext| ext == "idx") {
                 let pack_path = path.with_extension("pack");
-                if verify_pack::inspect_pack_files(&path, &pack_path).is_err() {
+                if inspect_pack_files_preserving_hash_kind(&path, &pack_path).is_err() {
                     continue;
                 }
                 let packed = list_idx_objects(&path).map_err(|error| {
@@ -312,6 +317,29 @@ async fn collect_packed_objects(storage: &ClientStorage) -> CliResult<HashSet<Ob
     Ok(packed_objects)
 }
 
+struct HashKindRestoreGuard {
+    previous: HashKind,
+}
+
+impl HashKindRestoreGuard {
+    fn preserve() -> Self {
+        Self {
+            previous: get_hash_kind(),
+        }
+    }
+}
+
+impl Drop for HashKindRestoreGuard {
+    fn drop(&mut self) {
+        set_hash_kind(self.previous);
+    }
+}
+
+fn inspect_pack_files_preserving_hash_kind(idx_path: &Path, pack_path: &Path) -> CliResult<()> {
+    let _guard = HashKindRestoreGuard::preserve();
+    verify_pack::inspect_pack_files(idx_path, pack_path).map(|_| ())
+}
+
 /// List all objects contained in a pack index file.
 fn list_idx_objects(idx_path: &Path) -> io::Result<Vec<ObjectHash>> {
     let hash_size = get_hash_kind().size() as u64;
diff --git a/src/internal/db/migration.rs b/src/internal/db/migration.rs
index 7ba5ca162..12feaa874 100644
--- a/src/internal/db/migration.rs
+++ b/src/internal/db/migration.rs
@@ -40,6 +40,10 @@ use chrono::{DateTime, Utc};
 use sea_orm::{ConnectionTrait, DatabaseConnection, DbErr, Statement, TransactionTrait};
 use thiserror::Error;
 
+/// Embedded canonical SQLite schema used when tests or low-level callers run
+/// built-in migrations against an otherwise empty SQLite database.
+const BOOTSTRAP_SQL: &str = include_str!("../../../sql/sqlite_20260309_init.sql");
+
 /// One named, versioned schema change.
 ///
 /// `up` is required; `down` is optional and only used by
@@ -382,17 +386,35 @@ async fn ensure_schema_versions_table(conn: &DatabaseConnection) -> Result<(), M
 }
 
 async fn schema_versions_table_exists(conn: &DatabaseConnection) -> Result<bool, MigrationError> {
+    sqlite_schema_table_exists(conn, "schema_versions").await
+}
+
+async fn sqlite_schema_table_exists(
+    conn: &DatabaseConnection,
+    table: &str,
+) -> Result<bool, MigrationError> {
     let backend = conn.get_database_backend();
     let row = conn
         .query_one(Statement::from_sql_and_values(
             backend,
             "SELECT 1 FROM sqlite_master WHERE type = ? AND name = ? LIMIT 1",
-            ["table".into(), "schema_versions".into()],
+            ["table".into(), table.into()],
         ))
         .await?;
     Ok(row.is_some())
 }
 
+async fn ensure_bootstrap_schema(conn: &DatabaseConnection) -> Result<(), MigrationError> {
+    if sqlite_schema_table_exists(conn, "reference").await? {
+        return Ok(());
+    }
+
+    let backend = conn.get_database_backend();
+    conn.execute(Statement::from_string(backend, BOOTSTRAP_SQL))
+        .await?;
+    Ok(())
+}
+
 async fn max_schema_version(conn: &DatabaseConnection) -> Result<Option<i64>, MigrationError> {
     let backend = conn.get_database_backend();
     let row = conn
@@ -703,6 +725,9 @@ pub async fn current_builtin_schema_version_readonly(
 /// build errors and per-migration apply errors are surfaced through
 /// `anyhow::Error` so the call site can attach its own context.
 pub async fn run_builtin_migrations(conn: &DatabaseConnection) -> Result<Vec<i64>> {
+    ensure_bootstrap_schema(conn)
+        .await
+        .with_context(|| "failed to ensure bootstrap schema before built-in migrations")?;
     let runner =
         builtin_runner().with_context(|| "failed to build the built-in migration registry")?;
     runner
diff --git a/tests/command/prune_test.rs b/tests/command/prune_test.rs
index f758cf403..3a394ae59 100644
--- a/tests/command/prune_test.rs
+++ b/tests/command/prune_test.rs
@@ -43,8 +43,16 @@ fn object_exists(repo: &Path, hash: &str) -> bool {
 
 /// Create a loose blob that is not referenced by any refs, index, or reflog.
 fn create_unreachable_blob(repo: &Path, content: &str) -> ObjectHash {
+    create_unreachable_blob_with_hash_kind(repo, content, HashKind::Sha1)
+}
+
+fn create_unreachable_blob_with_hash_kind(
+    repo: &Path,
+    content: &str,
+    hash_kind: HashKind,
+) -> ObjectHash {
     let _guard = ChangeDirGuard::new(repo);
-    let _hash_guard = set_hash_kind_for_test(HashKind::Sha1);
+    let _hash_guard = set_hash_kind_for_test(hash_kind);
     let blob = Blob::from_content(content);
     save_object(&blob, &blob.id).expect("failed to save blob");
     blob.id
@@ -335,6 +343,33 @@ fn test_prune_removes_synced_object_index_row() {
     );
 }
 
+#[test]
+#[serial]
+/// Tests direct prune respects an active GC lock before deleting objects.
+fn test_prune_rejects_active_gc_lock() {
+    let repo = create_committed_repo_via_cli();
+    let lock_path = repo
+        .path()
+        .join(libra::utils::util::ROOT_DIR)
+        .join("gc.lock");
+    fs::write(
+        &lock_path,
+        format!("pid={}\ntoken=test-lock\n", std::process::id()),
+    )
+    .expect("failed to write gc lock");
+
+    let output = run_libra_command(&["prune"], repo.path());
+    assert!(
+        !output.status.success(),
+        "prune should fail while gc lock is active"
+    );
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("gc is already running"),
+        "expected gc lock conflict, got: {stderr}"
+    );
+}
+
 #[test]
 #[serial]
 /// Tests --dry-run reports prunable objects without deleting them.
@@ -569,6 +604,38 @@ fn test_prune_orphan_packed_v1_keeps_reachable_duplicate() {
     assert!(object_exists(repo.path(), &head));
 }
 
+#[test]
+#[serial]
+/// Tests stale SHA-1 pack indexes do not poison SHA-256 loose-object scans.
+fn test_prune_stale_sha1_idx_preserves_sha256_hash_kind() {
+    let repo = tempdir().expect("failed to create repository root");
+    let init = run_libra_command(&["init", "--object-format", "sha256"], repo.path());
+    assert_cli_success(&init, "failed to initialize sha256 repository");
+    configure_identity_via_cli(repo.path());
+
+    fs::write(repo.path().join("tracked.txt"), "tracked\n").expect("failed to write tracked file");
+    let add = run_libra_command(&["add", ".libraignore", "tracked.txt"], repo.path());
+    assert_cli_success(&add, "failed to add tracked file");
+    let commit = run_libra_command(&["commit", "-m", "base", "--no-verify"], repo.path());
+    assert_cli_success(&commit, "failed to create base commit");
+
+    let unreachable =
+        create_unreachable_blob_with_hash_kind(repo.path(), "sha256-garbage", HashKind::Sha256);
+    assert!(object_exists(repo.path(), &unreachable.to_string()));
+
+    let sha1_guard = set_hash_kind_for_test(HashKind::Sha1);
+    let stale_sha1 = ObjectHash::from_bytes(&[1u8; 20]).expect("sha1 test hash should parse");
+    write_fake_idx_v2(repo.path(), &[stale_sha1]);
+    drop(sha1_guard);
+
+    let output = run_libra_command(&["prune"], repo.path());
+    assert_cli_success(&output, "prune should succeed");
+    assert!(
+        !object_exists(repo.path(), &unreachable.to_string()),
+        "unreachable sha256 loose object should be pruned after stale sha1 idx probe"
+    );
+}
+
 #[test]
 #[serial]
 /// Tests prune removes a batch of unreachable loose blobs.

From e373fc4e610b7019ce9b78b923b44860f98148d4 Mon Sep 17 00:00:00 2001
From: marshawcoco <marshawcoco@gmail.com>
Date: Thu, 25 Jun 2026 08:42:57 +0000
Subject: [PATCH 6/7] fix(prune): harden public object traversal

Signed-off-by: marshawcoco <marshawcoco@gmail.com>
---
 src/command/prune.rs        | 27 ++++++++++++
 tests/command/prune_test.rs | 86 ++++++++++++++++++++++++++++++++++---
 2 files changed, 106 insertions(+), 7 deletions(-)

diff --git a/src/command/prune.rs b/src/command/prune.rs
index d038ff9d8..5b062e4b9 100644
--- a/src/command/prune.rs
+++ b/src/command/prune.rs
@@ -44,6 +44,7 @@ use crate::{
 
 const IDX_MAGIC: [u8; 4] = [0xFF, 0x74, 0x4F, 0x63];
 const FANOUT_LEN: u64 = 256 * 4;
+const GITLINK_INDEX_MODE: u32 = 0o160000;
 const TAG_REF_PREFIX: &str = "refs/tags/";
 
 const PRUNE_LONG_ABOUT: &str =
@@ -148,6 +149,7 @@ pub async fn execute_safe(args: PruneArgs, output: &OutputConfig) -> CliResult<(
     };
 
     let objects_dir = path::objects();
+    ensure_real_object_directory(&objects_dir)?;
     let objects_dir_existed = objects_dir.exists();
     let expire_before = parse_expire_cutoff(args.expire.as_deref())?;
     if args.dry_run && !objects_dir_existed {
@@ -225,6 +227,28 @@ fn cleanup_dry_run_objects_dir(
     Ok(())
 }
 
+fn ensure_real_object_directory(objects_dir: &Path) -> CliResult<()> {
+    match fs::symlink_metadata(objects_dir) {
+        Ok(metadata) if metadata.file_type().is_symlink() => Err(CliError::fatal(format!(
+            "refusing to traverse symlink object directory '{}'",
+            objects_dir.display()
+        ))
+        .with_stable_code(StableErrorCode::RepoCorrupt)),
+        Ok(metadata) if metadata.file_type().is_dir() => Ok(()),
+        Ok(_) => Err(CliError::fatal(format!(
+            "object directory '{}' is not a directory",
+            objects_dir.display()
+        ))
+        .with_stable_code(StableErrorCode::RepoCorrupt)),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(()),
+        Err(error) => Err(CliError::fatal(format!(
+            "failed to inspect object directory '{}': {error}",
+            objects_dir.display()
+        ))
+        .with_stable_code(StableErrorCode::IoReadFailed)),
+    }
+}
+
 /// Parse the `--expire` argument into a concrete cutoff time.
 fn parse_expire_cutoff(expire: Option<&str>) -> CliResult<PrunePolicy> {
     let Some(value) = expire else {
@@ -454,6 +478,9 @@ async fn collect_starting_points(
         })?;
         for stage in [0, 1, 2, 3] {
             for entry in index.tracked_entries(stage) {
+                if entry.mode == GITLINK_INDEX_MODE {
+                    continue;
+                }
                 starting_points.insert(entry.hash);
             }
         }
diff --git a/tests/command/prune_test.rs b/tests/command/prune_test.rs
index 3a394ae59..8d7caeacf 100644
--- a/tests/command/prune_test.rs
+++ b/tests/command/prune_test.rs
@@ -9,13 +9,16 @@ use std::{
 
 use git_internal::{
     hash::{HashKind, ObjectHash, set_hash_kind_for_test},
-    internal::object::{
-        blob::Blob,
-        commit::Commit,
-        signature::{Signature, SignatureType},
-        tag::Tag,
-        tree::{Tree, TreeItem, TreeItemMode},
-        types::ObjectType,
+    internal::{
+        index::{Index, IndexEntry},
+        object::{
+            blob::Blob,
+            commit::Commit,
+            signature::{Signature, SignatureType},
+            tag::Tag,
+            tree::{Tree, TreeItem, TreeItemMode},
+            types::ObjectType,
+        },
     },
 };
 use sea_orm::{ActiveModelTrait, ColumnTrait, EntityTrait, QueryFilter, Set};
@@ -80,6 +83,12 @@ fn insert_object_index_row(repo: &Path, hash: &ObjectHash, repo_id: &str, is_syn
     let runtime = tokio::runtime::Runtime::new().expect("runtime");
     runtime.block_on(async {
         let db_conn = libra::internal::db::get_db_conn_instance().await;
+        libra::internal::model::object_index::Entity::delete_many()
+            .filter(libra::internal::model::object_index::Column::OId.eq(hash.to_string()))
+            .filter(libra::internal::model::object_index::Column::RepoId.eq(repo_id))
+            .exec(&db_conn)
+            .await
+            .expect("clear existing object_index");
         let model = libra::internal::model::object_index::ActiveModel {
             o_id: Set(hash.to_string()),
             o_type: Set("blob".to_string()),
@@ -370,6 +379,69 @@ fn test_prune_rejects_active_gc_lock() {
     );
 }
 
+#[cfg(unix)]
+#[test]
+#[serial]
+/// Tests direct prune refuses a symlinked object directory before traversal.
+fn test_prune_rejects_symlink_object_directory() {
+    use std::os::unix::fs::symlink;
+
+    let repo = create_committed_repo_via_cli();
+    let blob = create_unreachable_blob(repo.path(), "symlinked-object-store");
+    let blob_path = loose_object_path(repo.path(), &blob.to_string());
+    assert!(blob_path.exists());
+
+    let storage_root = repo.path().join(libra::utils::util::ROOT_DIR);
+    let objects_dir = storage_root.join("objects");
+    let external_objects = repo.path().join("external-objects");
+    fs::rename(&objects_dir, &external_objects).expect("move object directory");
+    symlink(&external_objects, &objects_dir).expect("symlink object directory");
+
+    let output = run_libra_command(&["prune"], repo.path());
+    assert!(
+        !output.status.success(),
+        "prune should fail on symlinked object dir"
+    );
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    assert!(
+        stderr.contains("symlink object directory"),
+        "expected symlink object directory error, got: {stderr}"
+    );
+    assert!(
+        blob_path.exists(),
+        "prune must not delete through a symlinked object dir"
+    );
+}
+
+#[test]
+#[serial]
+/// Tests prune ignores gitlink index entries before walking roots.
+fn test_prune_skips_gitlink_index_entry() {
+    let repo = create_committed_repo_via_cli();
+    let blob = create_unreachable_blob(repo.path(), "gitlink-index");
+    let blob_path = loose_object_path(repo.path(), &blob.to_string());
+    assert!(blob_path.exists());
+
+    let _guard = ChangeDirGuard::new(repo.path());
+    let _hash_guard = set_hash_kind_for_test(HashKind::Sha1);
+    let gitlink = ObjectHash::from_bytes(&[0x42; 20]).expect("gitlink oid");
+    let mut entry = IndexEntry::new_from_blob("submodule".to_string(), gitlink, 0);
+    entry.mode = 0o160000;
+    let mut index = Index::new();
+    index.add(entry);
+    index
+        .to_file(libra::utils::path::index())
+        .expect("write index");
+    drop(_guard);
+
+    let output = run_libra_command(&["prune"], repo.path());
+    assert_cli_success(&output, "prune should ignore gitlink index entries");
+    assert!(
+        !blob_path.exists(),
+        "unreachable blob should still be pruned"
+    );
+}
+
 #[test]
 #[serial]
 /// Tests --dry-run reports prunable objects without deleting them.

From 2f5040583859c32bbf9ff144ac13f6812fce854c Mon Sep 17 00:00:00 2001
From: marshawcoco <marshawcoco@gmail.com>
Date: Thu, 25 Jun 2026 15:47:52 +0000
Subject: [PATCH 7/7] fix(gc): align dry-run reachability with reflog expiry

Signed-off-by: marshawcoco <marshawcoco@gmail.com>
---
 src/command/gc.rs                     | 146 ++++++++++++++++++++++----
 src/command/prune.rs                  |  10 +-
 tests/agent_capture_migration_test.rs |   9 +-
 tests/command/prune_test.rs           |  37 +++++++
 4 files changed, 180 insertions(+), 22 deletions(-)

diff --git a/src/command/gc.rs b/src/command/gc.rs
index 59d31f7e6..69e286181 100644
--- a/src/command/gc.rs
+++ b/src/command/gc.rs
@@ -349,8 +349,9 @@ async fn run_gc(args: &GcArgs) -> CliResult<GcOutput> {
     } else {
         ClientStorage::init(objects_dir)
     };
-    let (reflogs, reflog_warnings) = expire_reflogs_for_gc(&storage, args.dry_run).await?;
-    let mut reachability = collect_reachability(&storage).await?;
+    let (reflogs, reflog_warnings, projected_reflog_roots) =
+        expire_reflogs_for_gc(&storage, args.dry_run).await?;
+    let mut reachability = collect_reachability(&storage, projected_reflog_roots.as_ref()).await?;
     reachability.warnings.extend(reflog_warnings);
     trace_reachable(&storage, &mut reachability);
     let skip_loose_prune = !args.dry_run && !reachability.warnings.is_empty();
@@ -427,12 +428,12 @@ async fn run_gc(args: &GcArgs) -> CliResult<GcOutput> {
 async fn expire_reflogs_for_gc(
     storage: &ClientStorage,
     dry_run: bool,
-) -> CliResult<(ReflogExpireStats, Vec<String>)> {
+) -> CliResult<(ReflogExpireStats, Vec<String>, Option<HashSet<ObjectHash>>)> {
     ensure_regular_repository_database()?;
     let db = get_db_conn_instance().await;
     let refs = reflog_ref_names(&db).await?;
     if refs.is_empty() {
-        return Ok((ReflogExpireStats::default(), Vec::new()));
+        return Ok((ReflogExpireStats::default(), Vec::new(), None));
     }
 
     let (expire, expire_unreachable) = expire_defaults_with_conn(&db)
@@ -445,7 +446,7 @@ async fn expire_reflogs_for_gc(
         ..Default::default()
     };
     if let Some(warning) = reflog_parent_traversal_warning(storage, &tips) {
-        return Ok((stats, vec![warning]));
+        return Ok((stats, vec![warning], None));
     }
 
     let options = ExpireOptions {
@@ -457,7 +458,17 @@ async fn expire_reflogs_for_gc(
         dry_run,
     };
 
+    let mut projected_roots = dry_run.then(HashSet::new);
     for ref_name in refs {
+        let entries = if dry_run {
+            Some(
+                ReflogStore::find_all(&db, &ref_name)
+                    .await
+                    .map_err(map_gc_reflog_error)?,
+            )
+        } else {
+            None
+        };
         let parent_storage = storage.clone();
         let commit_storage = storage.clone();
         let result = expire_reflog(
@@ -471,8 +482,25 @@ async fn expire_reflogs_for_gc(
         .map_err(map_gc_reflog_error)?;
         stats.pruned += result.pruned;
         stats.rewritten += result.rewritten;
+        if let (Some(entries), Some(projected_roots)) = (entries, projected_roots.as_mut()) {
+            let pruned = result
+                .pruned_entries
+                .iter()
+                .map(|entry| entry.index)
+                .collect::<HashSet<_>>();
+            for (index, entry) in entries.iter().enumerate() {
+                if pruned.contains(&index) {
+                    continue;
+                }
+                for raw in [entry.old_oid.as_str(), entry.new_oid.as_str()] {
+                    if !is_null_oid(raw) {
+                        projected_roots.insert(parse_stored_hash(raw, "projected reflog")?);
+                    }
+                }
+            }
+        }
     }
-    Ok((stats, Vec::new()))
+    Ok((stats, Vec::new(), projected_roots))
 }
 
 /// Enumerate reflog refs for the GC pre-prune expiration pass.
@@ -1008,10 +1036,14 @@ fn should_prune(path: &Path, policy: PrunePolicy) -> CliResult<bool> {
 }
 
 /// Collect loose objects and root object IDs before graph traversal.
-async fn collect_reachability(storage: &ClientStorage) -> CliResult<Reachability> {
+async fn collect_reachability(
+    storage: &ClientStorage,
+    projected_reflog_roots: Option<&HashSet<ObjectHash>>,
+) -> CliResult<Reachability> {
     ensure_real_object_directory(storage.base_path())?;
     let loose = list_loose_objects(storage.base_path())?;
-    let (roots, protected) = collect_roots_from_database().await?;
+    let (roots, protected) =
+        collect_roots_from_database_with_reflog_roots(projected_reflog_roots).await?;
     Ok(Reachability {
         loose,
         roots,
@@ -1265,6 +1297,12 @@ fn is_hex_prefix(prefix: &str) -> bool {
 /// Load root object IDs and non-reachability prune protections.
 pub(crate) async fn collect_roots_from_database()
 -> CliResult<(HashSet<ObjectHash>, HashSet<ObjectHash>)> {
+    collect_roots_from_database_with_reflog_roots(None).await
+}
+
+async fn collect_roots_from_database_with_reflog_roots(
+    projected_reflog_roots: Option<&HashSet<ObjectHash>>,
+) -> CliResult<(HashSet<ObjectHash>, HashSet<ObjectHash>)> {
     ensure_regular_repository_database()?;
     let db = get_db_conn_instance().await;
     let mut roots = HashSet::new();
@@ -1280,14 +1318,18 @@ pub(crate) async fn collect_roots_from_database()
         }
     }
 
-    let reflogs = reflog::Entity::find().all(&db).await.map_err(|error| {
-        CliError::fatal(format!("failed to load reflogs: {error}"))
-            .with_stable_code(StableErrorCode::IoReadFailed)
-    })?;
-    for entry in reflogs {
-        for raw in [entry.old_oid.as_str(), entry.new_oid.as_str()] {
-            if !is_null_oid(raw) {
-                roots.insert(parse_stored_hash(raw, "reflog")?);
+    if let Some(projected_reflog_roots) = projected_reflog_roots {
+        roots.extend(projected_reflog_roots.iter().copied());
+    } else {
+        let reflogs = reflog::Entity::find().all(&db).await.map_err(|error| {
+            CliError::fatal(format!("failed to load reflogs: {error}"))
+                .with_stable_code(StableErrorCode::IoReadFailed)
+        })?;
+        for entry in reflogs {
+            for raw in [entry.old_oid.as_str(), entry.new_oid.as_str()] {
+                if !is_null_oid(raw) {
+                    roots.insert(parse_stored_hash(raw, "reflog")?);
+                }
             }
         }
     }
@@ -3331,10 +3373,12 @@ mod tests {
         .unwrap();
 
         let storage = ClientStorage::init(path::objects());
-        let (stats, warnings) = expire_reflogs_for_gc(&storage, false).await.unwrap();
+        let (stats, warnings, projected_roots) =
+            expire_reflogs_for_gc(&storage, false).await.unwrap();
         let remaining = reflog::Entity::find().all(&db).await.unwrap();
 
         assert!(warnings.is_empty());
+        assert!(projected_roots.is_none());
         assert_eq!(stats.refs_scanned, 1);
         assert_eq!(stats.entries_scanned, 1);
         assert_eq!(stats.pruned, 1);
@@ -3373,10 +3417,12 @@ mod tests {
         .unwrap();
 
         let storage = ClientStorage::init(path::objects());
-        let (stats, warnings) = expire_reflogs_for_gc(&storage, true).await.unwrap();
+        let (stats, warnings, projected_roots) =
+            expire_reflogs_for_gc(&storage, true).await.unwrap();
         let remaining = reflog::Entity::find().all(&db).await.unwrap();
 
         assert!(warnings.is_empty());
+        assert_eq!(projected_roots.expect("dry-run projection").len(), 0);
         assert_eq!(stats.pruned, 1);
         assert_eq!(remaining.len(), 1);
     }
@@ -3433,9 +3479,11 @@ mod tests {
         }
 
         let storage = ClientStorage::init(path::objects());
-        let (stats, warnings) = expire_reflogs_for_gc(&storage, false).await.unwrap();
+        let (stats, warnings, projected_roots) =
+            expire_reflogs_for_gc(&storage, false).await.unwrap();
         let remaining = reflog::Entity::find().all(&db).await.unwrap();
 
+        assert!(projected_roots.is_none());
         assert_eq!(stats.refs_scanned, 1);
         assert_eq!(stats.entries_scanned, 2);
         assert_eq!(stats.pruned, 0);
@@ -3499,6 +3547,66 @@ mod tests {
         assert!(!storage.exist(&blob.id));
     }
 
+    #[tokio::test]
+    #[serial_test::serial]
+    /// Covers dry-run reachability using the projected post-expiry reflog set.
+    async fn run_gc_dry_run_prunes_objects_only_reachable_from_expired_reflog() {
+        let repo = tempdir().unwrap();
+        test::setup_with_new_libra_in(repo.path()).await;
+        let _guard = test::ChangeDirGuard::new(repo.path());
+        let db = get_db_conn_instance().await;
+
+        let tree = Tree {
+            id: test_hash(15),
+            tree_items: Vec::new(),
+        };
+        save_test_object(&tree, &tree.id).unwrap();
+        let commit = commit_with_tree(tree.id, Vec::new());
+        save_test_object(&commit, &commit.id).unwrap();
+
+        db.execute(Statement::from_sql_and_values(
+            DbBackend::Sqlite,
+            "INSERT INTO reflog \
+             (ref_name, old_oid, new_oid, timestamp, committer_name, committer_email, action, message) \
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?);",
+            [
+                "HEAD".into(),
+                test_hash(0).to_string().into(),
+                commit.id.to_string().into(),
+                1_i64.into(),
+                "tester".into(),
+                "tester@example.com".into(),
+                "commit".into(),
+                "expired entry".into(),
+            ],
+        ))
+        .await
+        .unwrap();
+
+        let output = run_gc(&GcArgs {
+            dry_run: true,
+            prune: "now".to_string(),
+            no_prune: false,
+            aggressive: false,
+            auto: false,
+            force: false,
+        })
+        .await
+        .unwrap();
+
+        let action = output
+            .unreachable_objects
+            .iter()
+            .find(|entry| entry.oid == commit.id.to_string())
+            .expect("commit should be reported as prunable after projected reflog expiry");
+        assert_eq!(action.action, GcAction::WouldPrune);
+        assert_eq!(output.reflogs.pruned, 1);
+        assert!(
+            reflog::Entity::find().all(&db).await.unwrap().len() == 1,
+            "dry-run must not delete the reflog row"
+        );
+    }
+
     #[tokio::test]
     #[serial_test::serial]
     /// Covers object-directory validation happening before storage initialization.
diff --git a/src/command/prune.rs b/src/command/prune.rs
index 5b062e4b9..72db81b8f 100644
--- a/src/command/prune.rs
+++ b/src/command/prune.rs
@@ -19,7 +19,12 @@ use git_internal::{
     hash::{HashKind, ObjectHash, get_hash_kind, set_hash_kind},
     internal::{
         index::Index,
-        object::{commit::Commit, tag::Tag, tree::Tree, types::ObjectType},
+        object::{
+            commit::Commit,
+            tag::Tag,
+            tree::{Tree, TreeItemMode},
+            types::ObjectType,
+        },
     },
     utils::read_sha,
 };
@@ -843,6 +848,9 @@ fn walk_object_refs(hash: &ObjectHash, storage: &ClientStorage) -> CliResult<Vec
                     .with_stable_code(StableErrorCode::RepoCorrupt)
             })?;
             for item in &tree.tree_items {
+                if item.mode == TreeItemMode::Commit {
+                    continue;
+                }
                 refs.push(item.id);
             }
         }
diff --git a/tests/agent_capture_migration_test.rs b/tests/agent_capture_migration_test.rs
index d7cde2162..a4dc262c3 100644
--- a/tests/agent_capture_migration_test.rs
+++ b/tests/agent_capture_migration_test.rs
@@ -81,6 +81,7 @@ async fn run_legacy_bootstrap(conn: &DatabaseConnection) {
 async fn agent_capture_creates_tables_and_indexes() {
     let (_dir, url) = fresh_db_url();
     let conn = connect(&url).await;
+    run_legacy_bootstrap(&conn).await;
     let runner = registered_runner();
     let applied = runner.run_pending(&conn).await.expect("run_pending");
     assert!(applied.contains(&2026050303));
@@ -98,6 +99,7 @@ async fn agent_capture_creates_tables_and_indexes() {
 async fn agent_capture_run_pending_is_idempotent() {
     let (_dir, url) = fresh_db_url();
     let conn = connect(&url).await;
+    run_legacy_bootstrap(&conn).await;
     let runner = registered_runner();
 
     let first = runner.run_pending(&conn).await.expect("run_pending #1");
@@ -118,6 +120,7 @@ async fn agent_capture_run_pending_is_idempotent() {
 async fn agent_capture_rollback_drops_tables_and_indexes_only() {
     let (_dir, url) = fresh_db_url();
     let conn = connect(&url).await;
+    run_legacy_bootstrap(&conn).await;
     let runner = registered_runner();
     runner.run_pending(&conn).await.expect("run_pending");
 
@@ -134,8 +137,8 @@ async fn agent_capture_rollback_drops_tables_and_indexes_only() {
     assert_eq!(
         rolled_back,
         vec![
-            2026061401, 2026060801, 2026060401, 2026060201, 2026053101, 2026052301, 2026050801,
-            2026050601, 2026050501, 2026050303
+            2026062301, 2026061401, 2026060801, 2026060401, 2026060201, 2026053101, 2026052301,
+            2026050801, 2026050601, 2026050501, 2026050303
         ]
     );
 
@@ -161,6 +164,7 @@ async fn agent_capture_rollback_drops_tables_and_indexes_only() {
 async fn agent_capture_up_down_up_round_trip() {
     let (_dir, url) = fresh_db_url();
     let conn = connect(&url).await;
+    run_legacy_bootstrap(&conn).await;
     let runner = registered_runner();
 
     runner.run_pending(&conn).await.expect("up #1");
@@ -264,6 +268,7 @@ async fn agent_capture_compatible_with_legacy_bootstrap() {
 async fn agent_capture_session_state_check_constraint_rejects_invalid() {
     let (_dir, url) = fresh_db_url();
     let conn = connect(&url).await;
+    run_legacy_bootstrap(&conn).await;
     let runner = registered_runner();
     runner.run_pending(&conn).await.expect("run_pending");
 
diff --git a/tests/command/prune_test.rs b/tests/command/prune_test.rs
index 8d7caeacf..f1d1c9187 100644
--- a/tests/command/prune_test.rs
+++ b/tests/command/prune_test.rs
@@ -139,6 +139,24 @@ fn create_unreachable_commit(repo: &Path, label: &str) -> (ObjectHash, ObjectHas
     (commit.id, tree.id, blob.id)
 }
 
+/// Create a loose commit whose tree contains a gitlink/submodule entry.
+fn create_commit_with_gitlink_tree(repo: &Path) -> ObjectHash {
+    let _guard = ChangeDirGuard::new(repo);
+    let _hash_guard = set_hash_kind_for_test(HashKind::Sha1);
+    let gitlink = ObjectHash::from_bytes(&[0x42; 20]).expect("gitlink oid");
+    let tree = Tree::from_tree_items(vec![TreeItem::new(
+        TreeItemMode::Commit,
+        gitlink,
+        "submodule".to_string(),
+    )])
+    .expect("failed to build gitlink tree");
+    save_object(&tree, &tree.id).expect("failed to save gitlink tree");
+
+    let commit = Commit::from_tree_id(tree.id, Vec::new(), "gitlink tree");
+    save_object(&commit, &commit.id).expect("failed to save gitlink commit");
+    commit.id
+}
+
 /// Write a minimal v2 pack index file that list_idx_objects can parse.
 fn write_fake_idx_v2(repo: &Path, hashes: &[ObjectHash]) -> PathBuf {
     let pack_dir = repo
@@ -442,6 +460,25 @@ fn test_prune_skips_gitlink_index_entry() {
     );
 }
 
+#[test]
+#[serial]
+/// Tests prune ignores gitlink tree entries while walking reachable objects.
+fn test_prune_skips_gitlink_tree_entry() {
+    let repo = create_committed_repo_via_cli();
+    let commit = create_commit_with_gitlink_tree(repo.path());
+    let blob = create_unreachable_blob(repo.path(), "gitlink-tree");
+    let blob_path = loose_object_path(repo.path(), &blob.to_string());
+    assert!(blob_path.exists());
+
+    let commit_arg = commit.to_string();
+    let output = run_libra_command(&["prune", &commit_arg], repo.path());
+    assert_cli_success(&output, "prune should ignore gitlink tree entries");
+    assert!(
+        !blob_path.exists(),
+        "unreachable blob should still be pruned"
+    );
+}
+
 #[test]
 #[serial]
 /// Tests --dry-run reports prunable objects without deleting them.