From 356af44c5a430cce8d79e0083f6668746ebdfb1f Mon Sep 17 00:00:00 2001
From: Quanyi Ma <eli@patch.sh>
Date: Mon, 6 Jul 2026 16:27:40 +0800
Subject: [PATCH 1/4] fix(reset): support git-style bare path reset

Signed-off-by: Quanyi Ma <eli@patch.sh>
---
 COMPATIBILITY.md                              |   2 +-
 docs/commands/reset.md                        |  21 ++-
 docs/commands/zh-CN/reset.md                  |  21 ++-
 docs/development/commands/reset.md            |   4 +-
 .../_parameter-tables.md                      |   2 +-
 .../cli.restore-reset-diff.md                 |   4 +-
 src/cli.rs                                    |  75 ++++++++++
 src/command/cherry_pick.rs                    |   3 +-
 src/command/reset.rs                          | 139 +++++++++++++++---
 src/internal/ai/review/launcher.rs            |   1 +
 tests/command/reset_test.rs                   | 112 ++++++++++++--
 11 files changed, 336 insertions(+), 48 deletions(-)

diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md
index 70d72a82f..304a03636 100644
--- a/COMPATIBILITY.md
+++ b/COMPATIBILITY.md
@@ -71,7 +71,7 @@ batch document.
 | merge | partial | fast-forward and single-head three-way merge supported; `-m <msg>`, `--ff-only`, `--no-ff`, `--squash`, `--no-commit`, `--no-edit` (accepted no-op; Libra never opens an editor for merge), `--stat`/`-n`/`--no-stat` (last-wins toggle; `--stat` prints a post-merge diffstat of the merge's changes, the default is no diffstat), `--no-progress` (accepted no-op; Libra's merge renders no progress meter), `--verify-signatures` (verify the merged tip's PGP signature against the local vault key — like `tag -v`, only signatures made by this repository's vault key can be validated; no external keyring) / `--no-verify-signatures` (the default; toggle pair, last wins), `--no-rerere-autoupdate` (accepted no-op — never auto-stages replayed resolutions; rerere IS auto-integrated when `rerere.enabled` is set, with staging following `rerere.autoUpdate` since merge does not expose the positive `--rerere-autoupdate`), and `--no-gpg-sign` (accepted no-op; Libra's merge never signs the merge commit) supported; the `merge.conflictStyle` config (`merge` default / `diff3` adds the `||||||| base` ancestor block to line-level text conflicts; honored by merge and cherry-pick; an unsupported value such as `zdiff3` is a hard error when a conflict must be rendered, exit 128) supported; Libra extensions: `--dry-run` (preview the outcome writing nothing — no HEAD/index/worktree/state/object write; exit 0 clean, exit 1 would-conflict with `would_conflict`+`conflicted_paths` in `--json`) and `--restart` (abort the in-progress conflicted merge — discarding resolution work like `--abort` — then re-run the same merge against the recorded target commit; original merge options not replayed); octopus/custom strategies, `--rerere-autoupdate`, and `-S`/`--gpg-sign` (signing the merge commit) deferred; `--autostash`/`--no-autostash` + `merge.autostash` config (lore.md 1.8, Git-faithful): a dirty tree (tracked changes incl. staged) is stashed into a HELD commit before the merge (not in `stash list` — the MERGE_AUTOSTASH model, sidecar `merge-autostash.json`), re-applied when the merge concludes (clean success, up-to-date, squash, start failure, `--continue`, `--abort`); a conflicted merge HOLDS it (also across `--restart` cycles); a conflicting re-apply promotes it into the stash list with a notice — changes are never lost; invalid `merge.autostash` is a hard error; JSON gains an additive `autostash: applied|stashed|kept` field lore.md 2.6: participates in the symmetric cross-op sequencer mutex — starting a `merge` is refused (`LBR-CONFLICT-002`) while any OTHER sequence is unresolved (and vice-versa). |
 | merge-base | partial | Prints the best common ancestor of two commits — a true LCA (a common ancestor that is not a strict ancestor of another), shared with `diff A...B` via `internal/merge_base.rs`; `--all` prints every lowest common ancestor, `--is-ancestor` tests ancestry (exit 0/1), `--json`/`--machine` supported. Exit 0 (base found / ancestry holds) / 1 (no common ancestor / not an ancestor; no output, matching Git) / 128 (unresolvable commit or wrong arg count). More than two commits, `--octopus`/`--independent`/`--fork-point` not exposed. `rebase` now computes its merge base through this shared LCA (no longer a first-found walk), and `log A...B` excludes the reachable-set intersection (correct for multiple merge bases) — the consolidation is complete |
 | merge-file | partial | File-level three-way merge of `<current> <base> <other>` reusing the same `diffy` merge as `merge` (markers labelled `ours`/`theirs`, `||||||| original` with `--diff3`); `-p`/`--stdout`, `--diff3`, `-q`/`--quiet`, `--json`/`--machine` supported; works outside a repository. Exit 0 (clean) / 1 (conflict, fixed at 1) / 128 (missing/unreadable/binary input). In-place writes back up the original under `.libra/merge-file-backup/` (kept on conflict). `-L <label>`, `--ours`/`--theirs`/`--union`, and `--marker-size` not exposed (deferred) |
-| reset | partial | `--soft`/`--mixed`/`--hard` and pathspec un-staging supported, with index-rollback on failure. `--pathspec-from-file`/`--pathspec-file-nul` supported for bulk/stdin pathspec input, but paths are taken literally — Git's default-mode C-style quoted-path decoding is intentionally not performed (use `--pathspec-file-nul` for special characters). `--no-refresh` is accepted as a no-op (Libra's reset never refreshes the index, so there is no refresh to skip; no `--refresh`). `--merge`/`--keep` remain unsupported (see [docs/commands/reset.md](docs/commands/reset.md) "Why no --merge/--keep?") |
+| reset | partial | `--soft`/`--mixed`/`--hard` and pathspec un-staging supported, with index-rollback on failure. Bare pathspecs follow Git disambiguation: `libra reset <path>` unstages from `HEAD`, `libra reset -- <path>` forces path interpretation for revision-like filenames, and a token that is both revision and filename is rejected as ambiguous (`LBR-CLI-002`). `--pathspec-from-file`/`--pathspec-file-nul` supported for bulk/stdin pathspec input, but paths are taken literally — Git's default-mode C-style quoted-path decoding is intentionally not performed (use `--pathspec-file-nul` for special characters). `--no-refresh` is accepted as a no-op (Libra's reset never refreshes the index, so there is no refresh to skip; no `--refresh`). `--merge`/`--keep` remain unsupported (see [docs/commands/reset.md](docs/commands/reset.md) "Why no --merge/--keep?") |
 | rev-parse | partial | basic revision parsing, `--verify`, `--short[=<n>]`, `--abbrev-ref`, `--symbolic-full-name` (resolve a spec to its full ref name — `refs/heads/…`/`refs/tags/…`/`refs/remotes/…`, or `HEAD` when detached; a valid non-ref object prints nothing, an unresolvable name exits 128 — Libra reports it on stderr rather than echoing the spec to stdout), `--symbolic` (echo a resolvable ref/revision/object-id spec verbatim — `main` stays `main`, not `refs/heads/main`; unresolvable names exit 128 like `--symbolic-full-name`), `--show-toplevel`, `--show-prefix`, `--show-cdup`, `--is-inside-work-tree`, `--is-inside-git-dir`, `--is-bare-repository`, `--git-dir`, `--absolute-git-dir`, `--sq` (shell-quote the resolved object name), the output-filter modes `--flags`/`--no-flags`/`--revs-only`/`--no-revs` (classify each arg as flag/revision/path and print a filtered subset), and multiple `<SPEC>` arguments (each resolved on its own line) supported; a `--` separator splits revisions from paths in all of these. **Intentional divergence:** combining `--verify`/`--short` (single-revision modes) with any output-filter flag is rejected with a usage error (LBR-CLI-002 / exit 129) — Git's behavior in that corner is ill-defined. Remaining output-filter (`--abbrev=<n>`) and parseopt modes are incomplete |
 | rev-list | partial | multi-revision reachability, `^` exclusions, `A..B`/`A...B` ranges, `--count`, `-n`/`--max-count`, `--skip`, `--since`/`--after`, `--until`/`--before`, parent-count filters and reset aliases, `--first-parent`, `--author`, `--committer`, `--grep`, path limitation after `--`, symmetric side filters (`--left-right`, `--left-only`, `--right-only`), cherry filters (`--cherry`, `--cherry-pick`, `--cherry-mark`), `--parents`, `--children`, `--timestamp`, and `--reverse` (limit-then-reverse output ordering), `--all` (seed the walk from every branch/remote/tag ref and HEAD), `--date-order` (no-op for Libra's default committer-date ordering; unlike Git, no topo constraint under date skew), and `--boundary` (append the frontier commits — parents of listed commits that are not themselves listed, whether excluded by a range or beyond a `--max-count`/`--skip` cut — each prefixed with `-` and carrying `--parents`/`--children`/`--timestamp` metadata, with Git-faithful merge handling under `--first-parent --parents` and `--children`, leading under `--reverse`, and counted by `--count`), and object-enumeration output (`--objects`, plus `--objects-edge`/`--objects-edge-aggressive` which also emit `-`-prefixed edge commits — the latter an alias, a documented narrowing) supported — objects are the deduplicated reachable trees/blobs printed after the commits as `<oid> <path>` (root tree empty path), byte-for-byte matching `git rev-list --objects`, with excluded-side objects treated as uninteresting (range/`^` closure), `-- <pathspec>` walk pruning, gitlinks skipped, and a hard error on a corrupt included tree |
 | describe | partial | basic describe, `--tags`, `--always`, `--abbrev`, `--exact-match`, `--long`, `--dirty[=<mark>]`, `--first-parent`, `--match`/`--exclude` (wax globs, ≤256 chars; exclude wins over match), `--candidates <n>` (n=0 ⇒ exact-match), `--all` (use any ref — branches/remotes/tags — with `heads/`/`remotes/`/`tags/` prefixes), and `--contains` (git name-rev: name a commit relative to the nearest descendant tag — `<tag>`, `<tag>~<n>`, or `<tag>~<n>^<m>~<k>`) supported |
diff --git a/docs/commands/reset.md b/docs/commands/reset.md
index 0a7f5e708..a2692a50b 100644
--- a/docs/commands/reset.md
+++ b/docs/commands/reset.md
@@ -6,6 +6,7 @@ Move `HEAD` and reset the index or working tree depending on the selected mode.
 
 ```
 libra reset [<target>] [--soft | --mixed | --hard]
+libra reset <pathspec>...
 libra reset [<target>] [--] <pathspec>...
 libra reset [<target>] --pathspec-from-file=<file> [--pathspec-file-nul]
 ```
@@ -18,7 +19,7 @@ libra reset [<target>] --pathspec-from-file=<file> [--pathspec-file-nul]
 - **`--mixed`** (default): moves HEAD and resets the index. The working tree is untouched, so changes appear as unstaged modifications. Useful for un-staging files.
 - **`--hard`**: moves HEAD, resets the index, and restores the working tree. All uncommitted changes are discarded. Useful for fully reverting to a known state.
 
-When pathspecs are provided, the command performs a targeted mixed reset: only the named files are reset in the index to match the target commit, without moving HEAD. This is the primary way to un-stage specific files. Pathspecs are incompatible with `--soft` and `--hard`.
+When pathspecs are provided, the command performs a targeted mixed reset: only the named files are reset in the index to match the target commit, without moving HEAD. This is the primary way to un-stage specific files. Like Git, a bare first positional that is a known path and not a revision is treated as a pathspec with target `HEAD`, so `libra reset src/lib.rs` is equivalent to `libra reset HEAD -- src/lib.rs`. If a token is both a revision and a filename, reset refuses it as ambiguous; use `libra reset <revision> -- <file>` for a target revision or `libra reset -- <file>` for a path. Pathspecs are incompatible with `--soft` and `--hard`.
 
 The default target is `HEAD`, making `libra reset` (with no arguments) equivalent to un-staging everything.
 
@@ -30,7 +31,7 @@ The default target is `HEAD`, making `libra reset` (with no arguments) equivalen
 | | `--soft` | | Move HEAD only; keep index and working tree |
 | | `--mixed` | | Move HEAD and reset index; keep working tree (default) |
 | | `--hard` | | Move HEAD, reset index, and restore working tree |
-| | `<pathspec>...` | positional (after `--`) | Specific files to reset in the index |
+| | `<pathspec>...` | positional, optionally after `--` | Specific files to reset in the index |
 | | `--pathspec-from-file` | `<file>` | Read pathspecs from a file (`-` for stdin) instead of the command line. Mutually exclusive with command-line pathspecs |
 | | `--pathspec-file-nul` | | Treat `--pathspec-from-file` input as NUL-separated rather than line-separated. No-op without `--pathspec-from-file` |
 | | `--no-refresh` | | Accepted for Git compatibility; a no-op in Libra (see below) |
@@ -63,10 +64,16 @@ libra reset HEAD~2
 libra reset --hard main
 
 # Un-stage a specific file
+libra reset src/lib.rs
+
+# Un-stage a revision-like filename
+libra reset -- HEAD
+
+# Un-stage a specific file from an explicit target
 libra reset HEAD -- src/lib.rs
 
 # Un-stage multiple files
-libra reset HEAD -- src/main.rs src/cli.rs
+libra reset src/main.rs src/cli.rs
 
 # Reset specific files to a prior commit
 libra reset abc1234 -- path/to/file.rs
@@ -87,6 +94,7 @@ libra reset --json --hard HEAD~1
 libra reset HEAD~1                    # Move HEAD and reset index to the previous commit
 libra reset --soft HEAD~2             # Move HEAD only, keep index and worktree
 libra reset --hard main               # Reset HEAD, index, and worktree to branch 'main'
+libra reset src/lib.rs                 # Unstage a path back to HEAD
 libra reset HEAD -- src/lib.rs        # Unstage a path back to HEAD
 libra reset --pathspec-from-file=paths.txt   # Unstage paths read from a file ('-' for stdin)
 libra reset --json --hard HEAD~1      # Structured JSON output for agents
@@ -159,7 +167,7 @@ Pathspec reset:
 
 ### Why reject pathspecs with --soft/--hard?
 
-- **`--soft` + pathspecs**: `--soft` by definition only moves HEAD and touches nothing else. Resetting individual file index entries contradicts the "HEAD only" contract. If you want to un-stage specific files, use the default mixed mode: `libra reset HEAD -- file`.
+- **`--soft` + pathspecs**: `--soft` by definition only moves HEAD and touches nothing else. Resetting individual file index entries contradicts the "HEAD only" contract. If you want to un-stage specific files, use the default mixed mode: `libra reset file` or `libra reset HEAD -- file`.
 - **`--hard` + pathspecs**: `--hard` restores the entire working tree to match the target commit. Selectively restoring only some files while leaving others in a different state would create a confusing hybrid that is neither "fully reset" nor "index-only reset." For selective file restoration, use `libra restore --source <commit> -- file`.
 
 This restriction makes the three modes unambiguous: soft touches HEAD, mixed touches HEAD + index, hard touches HEAD + index + worktree. Pathspecs operate orthogonally at the index level only.
@@ -185,7 +193,7 @@ Libra favors explicit, composable commands over implicit multi-step operations h
 | Mixed reset (default) | `git reset <target>` | `libra reset <target>` | N/A (jj has no staging area) |
 | Soft reset | `git reset --soft <target>` | `libra reset --soft <target>` | N/A |
 | Hard reset | `git reset --hard <target>` | `libra reset --hard <target>` | `jj restore --from <rev>` |
-| Un-stage files | `git reset HEAD -- <file>` | `libra reset HEAD -- <file>` | N/A (no staging area) |
+| Un-stage files | `git reset <file>` / `git reset HEAD -- <file>` | `libra reset <file>` / `libra reset HEAD -- <file>` | N/A (no staging area) |
 | Merge reset | `git reset --merge <target>` | Not supported | N/A |
 | Keep reset | `git reset --keep <target>` | Not supported | N/A |
 | Pathspec from file | `git reset --pathspec-from-file=<f>` | `libra reset --pathspec-from-file=<f>` (literal paths; no C-style quote decoding) | N/A |
@@ -193,7 +201,7 @@ Libra favors explicit, composable commands over implicit multi-step operations h
 | Index refresh control | `git reset --[no-]refresh` | `--no-refresh` accepted as a no-op; no `--refresh` | N/A |
 | Default target | HEAD | HEAD | N/A |
 | Structured output | No | `--json` / `--machine` | `--template` |
-| Pathspec + soft | Allowed (un-stages) | Rejected (`LBR-CLI-002`) | N/A |
+| Pathspec + soft | Rejected | Rejected (`LBR-CLI-002`) | N/A |
 | Pathspec + hard | Rejected | Rejected (`LBR-CLI-002`) | N/A |
 | Pathspec from file + CLI pathspec | Rejected | Rejected (`LBR-CLI-002`) | N/A |
 | Rollback on failure | No | Attempts index rollback | N/A (operation log undo) |
@@ -204,6 +212,7 @@ Libra favors explicit, composable commands over implicit multi-step operations h
 |----------|-----------|------|
 | Not a libra repository | `LBR-REPO-001` | "run 'libra init' to create a repository in the current directory." |
 | Invalid revision | `LBR-CLI-003` | "check the revision name and try again." |
+| Ambiguous revision/path token | `LBR-CLI-002` | "use '--' to separate paths from revisions, like 'libra reset <revision> -- <file>' or 'libra reset -- <file>'." |
 | HEAD is unborn | `LBR-REPO-003` | "create a commit first before resetting HEAD." |
 | Failed to resolve HEAD | `LBR-IO-001` | "check whether the repository database is readable." |
 | HEAD reference corrupt | `LBR-REPO-002` | "the HEAD reference or branch metadata may be corrupted." |
diff --git a/docs/commands/zh-CN/reset.md b/docs/commands/zh-CN/reset.md
index f5486e9c1..c309b9a0b 100644
--- a/docs/commands/zh-CN/reset.md
+++ b/docs/commands/zh-CN/reset.md
@@ -6,6 +6,7 @@
 
 ```
 libra reset [<target>] [--soft | --mixed | --hard]
+libra reset <pathspec>...
 libra reset [<target>] [--] <pathspec>...
 ```
 
@@ -17,7 +18,7 @@ libra reset [<target>] [--] <pathspec>...
 - **`--mixed`**（默认）：移动 HEAD 并重置索引。工作树保持不变，因此更改表现为未暂存修改。适合取消暂存文件。
 - **`--hard`**：移动 HEAD、重置索引并恢复工作树。所有未提交更改都会被丢弃。适合完全回到已知状态。
 
-提供 pathspec 时，命令执行有针对性的 mixed reset：只将命名文件在索引中重置为匹配目标提交，不移动 HEAD。这是取消暂存特定文件的主要方式。Pathspec 与 `--soft` 和 `--hard` 不兼容。
+提供 pathspec 时，命令执行有针对性的 mixed reset：只将命名文件在索引中重置为匹配目标提交，不移动 HEAD。这是取消暂存特定文件的主要方式。与 Git 一样，如果第一个裸位置参数是已知路径且不是 revision，`libra reset src/lib.rs` 会按 `HEAD` 目标的 pathspec reset 处理，等价于 `libra reset HEAD -- src/lib.rs`。如果同一个 token 既是 revision 又是文件名，reset 会拒绝猜测并报歧义；要把它作为目标 revision，请使用 `libra reset <revision> -- <file>`，要把它作为路径，请使用 `libra reset -- <file>`。Pathspec 与 `--soft` 和 `--hard` 不兼容。
 
 默认目标是 `HEAD`，因此不带参数的 `libra reset` 等价于取消暂存所有内容。
 
@@ -29,7 +30,7 @@ libra reset [<target>] [--] <pathspec>...
 | | `--soft` | | 只移动 HEAD；保留索引和工作树 |
 | | `--mixed` | | 移动 HEAD 并重置索引；保留工作树（默认） |
 | | `--hard` | | 移动 HEAD、重置索引并恢复工作树 |
-| | `<pathspec>...` | `--` 之后的位置参数 | 要在索引中重置的特定文件 |
+| | `<pathspec>...` | 位置参数，可放在 `--` 之后 | 要在索引中重置的特定文件 |
 
 ### 标志示例
 
@@ -47,10 +48,16 @@ libra reset HEAD~2
 libra reset --hard main
 
 # 取消暂存特定文件
+libra reset src/lib.rs
+
+# 取消暂存一个看起来像 revision 的文件名
+libra reset -- HEAD
+
+# 从显式目标取消暂存特定文件
 libra reset HEAD -- src/lib.rs
 
 # 取消暂存多个文件
-libra reset HEAD -- src/main.rs src/cli.rs
+libra reset src/main.rs src/cli.rs
 
 # 将特定文件重置到先前提交
 libra reset abc1234 -- path/to/file.rs
@@ -65,6 +72,7 @@ libra reset --json --hard HEAD~1
 libra reset HEAD~1                    # 移动 HEAD 并将索引重置到上一个提交
 libra reset --soft HEAD~2             # 只移动 HEAD，保留索引和工作树
 libra reset --hard main               # 将 HEAD、索引和工作树重置到分支 'main'
+libra reset src/lib.rs                 # 将路径取消暂存回 HEAD
 libra reset HEAD -- src/lib.rs        # 将路径取消暂存回 HEAD
 libra reset --json --hard HEAD~1      # 面向代理的结构化 JSON 输出
 ```
@@ -136,7 +144,7 @@ Pathspec reset：
 
 ### 为什么拒绝 pathspec 与 --soft/--hard 组合？
 
-- **`--soft` + pathspecs**：`--soft` 按定义只移动 HEAD，不触碰其他内容。重置单个文件索引条目违背“仅 HEAD”的契约。如果要取消暂存特定文件，请使用默认 mixed 模式：`libra reset HEAD -- file`。
+- **`--soft` + pathspecs**：`--soft` 按定义只移动 HEAD，不触碰其他内容。重置单个文件索引条目违背“仅 HEAD”的契约。如果要取消暂存特定文件，请使用默认 mixed 模式：`libra reset file` 或 `libra reset HEAD -- file`。
 - **`--hard` + pathspecs**：`--hard` 将整个工作树恢复为匹配目标提交。只选择性恢复一些文件，同时让其他文件处于不同状态，会产生令人困惑的混合状态，既不是“完全 reset”，也不是“仅索引 reset”。对于选择性文件恢复，请使用 `libra restore --source <commit> -- file`。
 
 该限制让三种模式无歧义：soft 触碰 HEAD，mixed 触碰 HEAD + index，hard 触碰 HEAD + index + worktree。Pathspec 正交地只在索引层面操作。
@@ -162,12 +170,12 @@ Libra 偏好显式、可组合命令，而不是隐藏在单个标志背后的
 | Mixed reset（默认） | `git reset <target>` | `libra reset <target>` | N/A（jj 没有暂存区） |
 | Soft reset | `git reset --soft <target>` | `libra reset --soft <target>` | N/A |
 | Hard reset | `git reset --hard <target>` | `libra reset --hard <target>` | `jj restore --from <rev>` |
-| 取消暂存文件 | `git reset HEAD -- <file>` | `libra reset HEAD -- <file>` | N/A（无暂存区） |
+| 取消暂存文件 | `git reset <file>` / `git reset HEAD -- <file>` | `libra reset <file>` / `libra reset HEAD -- <file>` | N/A（无暂存区） |
 | Merge reset | `git reset --merge <target>` | 不支持 | N/A |
 | Keep reset | `git reset --keep <target>` | 不支持 | N/A |
 | 默认目标 | HEAD | HEAD | N/A |
 | 结构化输出 | 无 | `--json` / `--machine` | `--template` |
-| Pathspec + soft | 允许（取消暂存） | 拒绝（`LBR-CLI-002`） | N/A |
+| Pathspec + soft | 拒绝 | 拒绝（`LBR-CLI-002`） | N/A |
 | Pathspec + hard | 拒绝 | 拒绝（`LBR-CLI-002`） | N/A |
 | 失败回滚 | 无 | 尝试索引回滚 | N/A（operation log undo） |
 
@@ -177,6 +185,7 @@ Libra 偏好显式、可组合命令，而不是隐藏在单个标志背后的
 |----------|-----------|------|
 | 不是 libra 仓库 | `LBR-REPO-001` | "run 'libra init' to create a repository in the current directory." |
 | 无效修订 | `LBR-CLI-003` | "check the revision name and try again." |
+| revision/path token 歧义 | `LBR-CLI-002` | "use '--' to separate paths from revisions, like 'libra reset <revision> -- <file>' or 'libra reset -- <file>'." |
 | HEAD unborn | `LBR-REPO-003` | "create a commit first before resetting HEAD." |
 | 无法解析 HEAD | `LBR-IO-001` | "check whether the repository database is readable." |
 | HEAD 引用损坏 | `LBR-REPO-002` | "the HEAD reference or branch metadata may be corrupted." |
diff --git a/docs/development/commands/reset.md b/docs/development/commands/reset.md
index 3043c0c54..d09f097a5 100644
--- a/docs/development/commands/reset.md
+++ b/docs/development/commands/reset.md
@@ -45,8 +45,8 @@ flowchart TD
 
 - 公开状态：已公开；模块状态：已导出。
 - 用户文档：`docs/commands/reset.md`。
-- Synopsis：`libra reset [--soft | --mixed | --hard] [<target>] [-- <pathspec>...]`；`libra reset [<target>] --pathspec-from-file=<file> [--pathspec-file-nul]`。
-- 公开参数/子命令包括：`[<target>]`、`--soft`、`--mixed`、`--hard`、`[<pathspec>...]`、`--pathspec-from-file=<file>`、`--pathspec-file-nul`、`--no-refresh`。
+- Synopsis：`libra reset [--soft | --mixed | --hard] [<target>]`；`libra reset <pathspec>...`；`libra reset [<target>] [--] <pathspec>...`；`libra reset [<target>] --pathspec-from-file=<file> [--pathspec-file-nul]`。
+- 公开参数/子命令包括：`[<target>]`、`--soft`、`--mixed`、`--hard`、`[<pathspec>...]`、`--pathspec-from-file=<file>`、`--pathspec-file-nul`、`--no-refresh`。裸路径兼容 Git：`libra reset <path>` 以 `HEAD` 为目标取消暂存；`libra reset -- <path>` 强制按路径解释 revision-like 文件名；同一 token 同时是 revision 和文件名时返回歧义错误 `LBR-CLI-002`。
 
 
 ## 还未实现的功能
diff --git a/docs/development/integration/integration-scenarios/_parameter-tables.md b/docs/development/integration/integration-scenarios/_parameter-tables.md
index d4fb33340..b4272fd85 100644
--- a/docs/development/integration/integration-scenarios/_parameter-tables.md
+++ b/docs/development/integration/integration-scenarios/_parameter-tables.md
@@ -77,7 +77,7 @@
 | `restore --overlay` | `cli.restore-reset-diff` | 已实现：overlay 模式仅创建/更新 source 中的路径、不移除 source 中缺失的已跟踪路径，runner 正向断言成功 |
 | `restore --no-overlay` | `cli.restore-reset-diff` | 已实现：与 `--overlay` 构成 last-wins 切换，默认行为（移除 source 中缺失路径），runner 正向断言成功 |
 | `restore --pathspec-from-file` | `cli.restore-reset-diff` | 已实现；负向步骤因 pathspec 文件缺失而失败（非「未实现」），runner 负向断言 |
-| `reset HEAD -- <path>` | `cli.restore-reset-diff` | 路径级 reset 只取消暂存 |
+| `reset <path>` / `reset HEAD -- <path>` | `cli.restore-reset-diff` | 路径级 reset 只取消暂存；revision/path 同名时用 `--` 消歧 |
 | `reset --soft` | `cli.restore-reset-diff` | 只移动 HEAD，保留 index/工作区 |
 | `reset --mixed` | `cli.restore-reset-diff` | 移动 HEAD 并重置 index |
 | `reset --hard` | `cli.restore-reset-diff` | HEAD、index、工作区全部回到目标 revision |
diff --git a/docs/development/integration/integration-scenarios/cli.restore-reset-diff.md b/docs/development/integration/integration-scenarios/cli.restore-reset-diff.md
index dde60a689..959e25cdb 100644
--- a/docs/development/integration/integration-scenarios/cli.restore-reset-diff.md
+++ b/docs/development/integration/integration-scenarios/cli.restore-reset-diff.md
@@ -32,7 +32,7 @@ libra restore --worktree tracked.txt
 
 printf 'second\n' > tracked.txt
 libra add tracked.txt
-libra reset HEAD -- tracked.txt
+libra reset tracked.txt
 libra add tracked.txt
 libra commit -m "second" --no-verify
 libra diff --old HEAD~1 --new HEAD --numstat
@@ -70,6 +70,6 @@ libra fsck --connectivity-only
 
 - `diff` 在 unstaged、staged、revision-to-revision、文件输出和 JSON 输出路径中返回可观察差异。
 - `restore --staged` 取消暂存，`restore --worktree` 和 `restore --source` 恢复工作区内容。
-- `reset HEAD -- <path>` 只取消暂存，`--soft`、`--mixed`、`--hard` 覆盖当前支持的 HEAD/index/worktree 行为。
+- `reset <path>` / `reset HEAD -- <path>` 只取消暂存；revision/path 同名时必须用 `--` 消歧；`--soft`、`--mixed`、`--hard` 覆盖当前支持的 HEAD/index/worktree 行为。
 - 未实现参数必须返回稳定错误，且错误路径不能移动 HEAD 或改写目标文件。
 - 场景结束时运行 `fsck --connectivity-only`。
diff --git a/src/cli.rs b/src/cli.rs
index d360893d3..6ccf3982a 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1024,6 +1024,80 @@ fn rewrite_index_pack_progress_args(args: Vec<String>) -> Vec<String> {
     out
 }
 
+fn rewrite_reset_pathspec_separator_args(args: Vec<String>) -> Vec<String> {
+    let subcommand = find_subcommand_index(&args);
+    let Some((reset_index, from_double_dash)) = subcommand else {
+        return args;
+    };
+    if !matches!(args.get(reset_index), Some(name) if name == "reset") {
+        return args;
+    }
+
+    let separator_index = args
+        .iter()
+        .enumerate()
+        .skip(reset_index + 1)
+        .find_map(|(index, arg)| (arg == "--").then_some(index));
+    let Some(separator_index) = separator_index else {
+        return args;
+    };
+
+    let has_target_before_separator =
+        reset_has_positional_target_before_separator(&args, reset_index + 1, separator_index);
+    let mut out = Vec::with_capacity(args.len() + usize::from(!has_target_before_separator));
+    if from_double_dash {
+        for (idx, arg) in args.iter().enumerate().take(reset_index + 1) {
+            if idx + 1 == reset_index && arg == "--" {
+                continue;
+            }
+            out.push(arg.clone());
+        }
+    } else {
+        out.extend(args.iter().take(reset_index + 1).cloned());
+    }
+
+    for arg in args.iter().take(separator_index).skip(reset_index + 1) {
+        out.push(arg.clone());
+    }
+    out.push(format!(
+        "--{}",
+        command::reset::RESET_PATHSPEC_SEPARATOR_FLAG
+    ));
+    if !has_target_before_separator && args.get(separator_index + 1).is_some() {
+        out.push("HEAD".to_string());
+    }
+    out.extend(args.iter().skip(separator_index + 1).cloned());
+    out
+}
+
+fn reset_has_positional_target_before_separator(
+    args: &[String],
+    start: usize,
+    separator_index: usize,
+) -> bool {
+    let mut index = start;
+    while index < separator_index {
+        let arg = &args[index];
+        if reset_flag_takes_separate_value(arg) {
+            index += 2;
+            continue;
+        }
+        if arg.starts_with('-') {
+            index += 1;
+            continue;
+        }
+        return true;
+    }
+    false
+}
+
+fn reset_flag_takes_separate_value(arg: &str) -> bool {
+    matches!(
+        arg,
+        "--pathspec-from-file" | "--color" | "--progress" | "--max-connections"
+    )
+}
+
 /// Locate the first non-flag token in `args` and return its index plus whether it was
 /// produced by an explicit `--` separator.
 ///
@@ -1547,6 +1621,7 @@ pub async fn parse_async(args: Option<&[&str]>) -> CliResult<()> {
     };
     let argv = rewrite_log_short_number_args(argv);
     let argv = rewrite_index_pack_progress_args(argv);
+    let argv = rewrite_reset_pathspec_separator_args(argv);
     prepare_cli_invocation_state();
     if is_error_codes_help_topic(&argv) {
         return print_error_codes_help();
diff --git a/src/command/cherry_pick.rs b/src/command/cherry_pick.rs
index 070605ed6..60b19a26c 100644
--- a/src/command/cherry_pick.rs
+++ b/src/command/cherry_pick.rs
@@ -701,11 +701,12 @@ async fn reset_hard(target: &str, output: &OutputConfig) -> Result<(), CherryPic
     let child = silent_child_output(output);
     crate::command::reset::execute_safe(
         crate::command::reset::ResetArgs {
-            target: target.to_string(),
+            target: Some(target.to_string()),
             soft: false,
             mixed: false,
             hard: true,
             pathspecs: Vec::new(),
+            pathspec_separator: false,
             pathspec_from_file: None,
             pathspec_file_nul: false,
             no_refresh: false,
diff --git a/src/command/reset.rs b/src/command/reset.rs
index 6e203dc75..9765aebf0 100644
--- a/src/command/reset.rs
+++ b/src/command/reset.rs
@@ -44,16 +44,19 @@ EXAMPLES:
     libra reset HEAD~1                    Move HEAD and reset index to the previous commit
     libra reset --soft HEAD~2             Move HEAD only, keep index and worktree
     libra reset --hard main               Reset HEAD, index, and worktree to branch 'main'
+    libra reset src/lib.rs                 Unstage a path back to HEAD
     libra reset HEAD -- src/lib.rs        Unstage a path back to HEAD
     libra reset --pathspec-from-file=paths.txt   Unstage paths read from a file ('-' for stdin)
     libra reset --json --hard HEAD~1      Structured JSON output for agents";
 
+pub(crate) const RESET_PATHSPEC_SEPARATOR_FLAG: &str = "__libra-reset-pathspec-separator";
+const DEFAULT_RESET_TARGET: &str = "HEAD";
+
 #[derive(Parser, Debug)]
 #[command(after_help = RESET_EXAMPLES)]
 pub struct ResetArgs {
     /// The commit to reset to (default: HEAD)
-    #[clap(default_value = "HEAD")]
-    pub target: String,
+    pub target: Option<String>,
 
     /// Soft reset: only move HEAD pointer
     #[clap(long, group = "mode")]
@@ -71,6 +74,12 @@ pub struct ResetArgs {
     #[clap(value_name = "PATH")]
     pub pathspecs: Vec<String>,
 
+    /// Internal flag injected by the top-level CLI when the user typed `--`
+    /// inside `reset` arguments. Clap does not preserve the separator itself,
+    /// but reset needs to distinguish `reset HEAD` from `reset -- HEAD`.
+    #[clap(long = RESET_PATHSPEC_SEPARATOR_FLAG, hide = true)]
+    pub pathspec_separator: bool,
+
     /// Read pathspecs from the given file (`-` for stdin), one per line (or
     /// NUL-separated with --pathspec-file-nul). Mutually exclusive with
     /// command-line pathspecs.
@@ -170,6 +179,9 @@ enum ResetError {
     #[error("{0}")]
     InvalidRevision(String),
 
+    #[error("ambiguous argument '{0}': both revision and filename")]
+    AmbiguousRevisionPath(String),
+
     #[error("Cannot reset: HEAD is unborn and points to no commit.")]
     HeadUnborn,
 
@@ -255,6 +267,7 @@ impl ResetError {
         match self {
             Self::NotInRepo => StableErrorCode::RepoNotFound,
             Self::InvalidRevision(_) => StableErrorCode::CliInvalidTarget,
+            Self::AmbiguousRevisionPath(_) => StableErrorCode::CliInvalidArguments,
             Self::HeadUnborn => StableErrorCode::RepoStateInvalid,
             Self::HeadRead(_) => StableErrorCode::IoReadFailed,
             Self::HeadCorrupt(_) => StableErrorCode::RepoCorrupt,
@@ -285,6 +298,9 @@ impl ResetError {
                 Some("run 'libra init' to create a repository in the current directory.")
             }
             Self::InvalidRevision(_) => Some("check the revision name and try again."),
+            Self::AmbiguousRevisionPath(_) => Some(
+                "use '--' to separate paths from revisions, like 'libra reset <revision> -- <file>' or 'libra reset -- <file>'.",
+            ),
             Self::HeadUnborn => Some("create a commit first before resetting HEAD."),
             Self::HeadRead(_) => Some("check whether the repository database is readable."),
             Self::HeadCorrupt(_) => Some("the HEAD reference or branch metadata may be corrupted."),
@@ -329,7 +345,8 @@ impl ResetError {
 
     fn is_command_usage(&self) -> bool {
         match self {
-            Self::PathspecWithSoft(_)
+            Self::AmbiguousRevisionPath(_)
+            | Self::PathspecWithSoft(_)
             | Self::PathspecWithHard
             | Self::PathspecSourceConflict
             | Self::PathspecOutsideWorkdir(_) => true,
@@ -394,14 +411,20 @@ async fn reject_reset_on_ai_managed_current_branch() -> Result<(), ResetError> {
     }
 }
 
+struct ResetRequest {
+    target: String,
+    pathspecs: Vec<String>,
+}
+
 async fn run_reset(args: ResetArgs) -> Result<ResetExecution, ResetError> {
     util::require_repo().map_err(|_| ResetError::NotInRepo)?;
+    let request = normalize_reset_request(&args).await?;
 
     // Refuse to reset onto a Libra-managed locked branch. `is_locked_revision`
     // strips `~` / `^` / `@` suffixes so attempts like `traces~1` or
     // `intent^` are still rejected.
-    if branch::is_locked_revision(&args.target) {
-        return Err(ResetError::LockedTarget(args.target.clone()));
+    if branch::is_locked_revision(&request.target) {
+        return Err(ResetError::LockedTarget(request.target.clone()));
     }
 
     let mode = if args.soft {
@@ -413,22 +436,16 @@ async fn run_reset(args: ResetArgs) -> Result<ResetExecution, ResetError> {
     };
     let previous_commit = Head::current_commit().await.map(|hash| hash.to_string());
 
-    // Effective pathspecs may come from the command line or from
-    // `--pathspec-from-file` (mutually exclusive; `-` reads stdin). Both
-    // sources flow through the same `reset_pathspecs` execution and
-    // containment checks below.
-    let effective_pathspecs = resolve_effective_pathspecs(&args)?;
-
-    if !effective_pathspecs.is_empty() {
+    if !request.pathspecs.is_empty() {
         if matches!(mode, ResetMode::Soft) {
-            return Err(ResetError::PathspecWithSoft(effective_pathspecs.join(" ")));
+            return Err(ResetError::PathspecWithSoft(request.pathspecs.join(" ")));
         }
         if matches!(mode, ResetMode::Hard) {
             return Err(ResetError::PathspecWithHard);
         }
 
-        let target_commit_id = resolve_commit(&args.target).await?;
-        let changed_paths = reset_pathspecs(&effective_pathspecs, &target_commit_id).await?;
+        let target_commit_id = resolve_commit(&request.target).await?;
+        let changed_paths = reset_pathspecs(&request.pathspecs, &target_commit_id).await?;
         let subject = load_commit_summary_or_warn(&target_commit_id);
         let commit = target_commit_id.to_string();
 
@@ -454,8 +471,8 @@ async fn run_reset(args: ResetArgs) -> Result<ResetExecution, ResetError> {
 
     reject_reset_on_ai_managed_current_branch().await?;
 
-    let target_commit_id = resolve_commit(&args.target).await?;
-    let reset_stats = perform_reset(target_commit_id, mode, &args.target).await?;
+    let target_commit_id = resolve_commit(&request.target).await?;
+    let reset_stats = perform_reset(target_commit_id, mode, &request.target).await?;
 
     let subject = load_commit_summary_or_warn(&target_commit_id);
     let commit = target_commit_id.to_string();
@@ -474,6 +491,82 @@ async fn run_reset(args: ResetArgs) -> Result<ResetExecution, ResetError> {
     })
 }
 
+async fn normalize_reset_request(args: &ResetArgs) -> Result<ResetRequest, ResetError> {
+    // Effective pathspecs may come from the command line or from
+    // `--pathspec-from-file` (mutually exclusive; `-` reads stdin). Both
+    // sources flow through the same `reset_pathspecs` execution and
+    // containment checks below.
+    let mut pathspecs = resolve_effective_pathspecs(args)?;
+    let target = args
+        .target
+        .as_deref()
+        .unwrap_or(DEFAULT_RESET_TARGET)
+        .to_string();
+
+    if args.pathspec_separator || args.target.is_none() || args.pathspec_from_file.is_some() {
+        return Ok(ResetRequest { target, pathspecs });
+    }
+
+    let Some(target_arg) = args.target.as_deref() else {
+        return Ok(ResetRequest { target, pathspecs });
+    };
+    let resolves_as_revision = target_resolves_as_revision(target_arg).await?;
+    let matches_path = pathspec_matches_known_path(target_arg).await?;
+
+    match (resolves_as_revision, matches_path) {
+        (true, true) => Err(ResetError::AmbiguousRevisionPath(target_arg.to_string())),
+        (true, false) => Ok(ResetRequest { target, pathspecs }),
+        (false, true) => {
+            pathspecs.insert(0, target_arg.to_string());
+            Ok(ResetRequest {
+                target: DEFAULT_RESET_TARGET.to_string(),
+                pathspecs,
+            })
+        }
+        (false, false) => Ok(ResetRequest { target, pathspecs }),
+    }
+}
+
+async fn target_resolves_as_revision(target: &str) -> Result<bool, ResetError> {
+    match resolve_commit(target).await {
+        Ok(_) => Ok(true),
+        Err(ResetError::InvalidRevision(_)) | Err(ResetError::HeadUnborn) => Ok(false),
+        Err(error) => Err(error),
+    }
+}
+
+async fn pathspec_matches_known_path(pathspec: &str) -> Result<bool, ResetError> {
+    let absolute = util::workdir_to_absolute(PathBuf::from(pathspec));
+    if absolute.exists() {
+        return Ok(true);
+    }
+    if !util::is_sub_path(&absolute, util::working_dir()) {
+        return Ok(false);
+    }
+
+    let relative_path = util::workdir_to_current(PathBuf::from(pathspec));
+    let path_str = relative_path
+        .to_str()
+        .ok_or_else(|| ResetError::InvalidPathspecEncoding(relative_path.display().to_string()))?;
+
+    let index = Index::load(path::index()).map_err(|e| ResetError::IndexLoad(e.to_string()))?;
+    if index.get(path_str, 0).is_some() {
+        return Ok(true);
+    }
+
+    let Some(head_commit_id) = Head::current_commit_result()
+        .await
+        .map_err(map_reset_head_commit_error)?
+    else {
+        return Ok(false);
+    };
+    let commit: Commit = load_object(&head_commit_id)
+        .map_err(|e| object_load_error("commit", head_commit_id.to_string(), e.to_string()))?;
+    let tree: Tree = load_object(&commit.tree_id)
+        .map_err(|e| object_load_error("tree", commit.tree_id.to_string(), e.to_string()))?;
+    find_tree_item(&tree, path_str).map(|item| item.is_some())
+}
+
 /// Reset specific files in the index to their state in the target commit.
 /// This function only affects the index, not the working directory.
 async fn reset_pathspecs(
@@ -1275,7 +1368,7 @@ mod tests {
     fn test_reset_args_parse() {
         let args = ResetArgs::try_parse_from(["reset", "--hard", "HEAD~1"]).unwrap();
         assert!(args.hard);
-        assert_eq!(args.target, "HEAD~1");
+        assert_eq!(args.target.as_deref(), Some("HEAD~1"));
     }
 
     /// Pin the `Display` format contract for static-message and
@@ -1305,6 +1398,10 @@ mod tests {
             ResetError::InvalidRevision("ambiguous revision 'a'".to_string()).to_string(),
             "ambiguous revision 'a'",
         );
+        assert_eq!(
+            ResetError::AmbiguousRevisionPath("HEAD".to_string()).to_string(),
+            "ambiguous argument 'HEAD': both revision and filename",
+        );
         assert_eq!(
             ResetError::RevisionRead("io error".to_string()).to_string(),
             "io error",
@@ -1348,7 +1445,7 @@ mod tests {
 
     /// Pin the `stable_code()` mapping for every variant of
     /// [`ResetError`]. The [`StableErrorCode`] is what `--json`
-    /// consumers branch on; ResetError has 20 variants spread across
+    /// consumers branch on; ResetError has 21 variants spread across
     /// repo-state (RepoNotFound / RepoStateInvalid / RepoCorrupt),
     /// I/O (IoReadFailed / IoWriteFailed), and CLI input
     /// (CliInvalidArguments / CliInvalidTarget) buckets. A future
@@ -1371,6 +1468,10 @@ mod tests {
             ResetError::InvalidRevision("ignored".to_string()).stable_code(),
             StableErrorCode::CliInvalidTarget,
         );
+        assert_eq!(
+            ResetError::AmbiguousRevisionPath("ignored".to_string()).stable_code(),
+            StableErrorCode::CliInvalidArguments,
+        );
         assert_eq!(
             ResetError::HeadUnborn.stable_code(),
             StableErrorCode::RepoStateInvalid,
diff --git a/src/internal/ai/review/launcher.rs b/src/internal/ai/review/launcher.rs
index 1d92e71c5..0e970d2a9 100644
--- a/src/internal/ai/review/launcher.rs
+++ b/src/internal/ai/review/launcher.rs
@@ -353,6 +353,7 @@ pub fn process_start_ticks(pid: u32) -> Option<u64> {
 /// safe anchor is the LAST `)` — everything after it is the
 /// space-separated tail starting at field 3 (`state`). Field 22 is
 /// therefore index 19 of that tail.
+#[cfg(any(target_os = "linux", test))]
 fn parse_stat_start_ticks(stat: &str) -> Option<u64> {
     let tail = &stat[stat.rfind(')')? + 1..];
     tail.split_whitespace().nth(19)?.parse().ok()
diff --git a/tests/command/reset_test.rs b/tests/command/reset_test.rs
index 439d6f8f5..96893997a 100644
--- a/tests/command/reset_test.rs
+++ b/tests/command/reset_test.rs
@@ -328,6 +328,88 @@ fn test_reset_json_pathspec_omits_previous_commit() {
     assert_eq!(pathspecs[0], "tracked.txt");
 }
 
+#[test]
+fn reset_bare_pathspec_unstages_file_like_git() {
+    // Given: a tracked file is modified and staged.
+    let repo = create_committed_repo_via_cli();
+    fs::write(repo.path().join("tracked.txt"), "tracked\nupdated\n").unwrap();
+    let add_output = run_libra_command(&["add", "tracked.txt"], repo.path());
+    assert_cli_success(&add_output, "stage tracked.txt");
+
+    // When: reset receives the file as a bare positional, matching `git reset <path>`.
+    let output = run_libra_command(&["reset", "tracked.txt"], repo.path());
+
+    // Then: the file is unstaged but the worktree modification remains.
+    assert_cli_success(&output, "reset tracked.txt");
+    let status = run_libra_command(&["status", "--short"], repo.path());
+    assert_cli_success(&status, "status --short");
+    assert_eq!(String::from_utf8_lossy(&status.stdout), " M tracked.txt\n");
+}
+
+#[test]
+fn reset_double_dash_pathspec_unstages_file_named_like_revision() {
+    // Given: a tracked file is literally named HEAD and has staged content.
+    let repo = create_committed_repo_via_cli();
+    fs::write(repo.path().join("HEAD"), "head file\n").unwrap();
+    let add = run_libra_command(&["add", "HEAD"], repo.path());
+    assert_cli_success(&add, "add HEAD file");
+    let commit = run_libra_command(
+        &["commit", "-m", "add head file", "--no-verify"],
+        repo.path(),
+    );
+    assert_cli_success(&commit, "commit HEAD file");
+    fs::write(repo.path().join("HEAD"), "head file\nupdated\n").unwrap();
+    let add = run_libra_command(&["add", "HEAD"], repo.path());
+    assert_cli_success(&add, "stage HEAD file update");
+
+    // When: `--` explicitly marks the following token as a pathspec.
+    let output = run_libra_command(&["reset", "--", "HEAD"], repo.path());
+
+    // Then: the revision-like filename is treated as a path and unstaged.
+    assert_cli_success(&output, "reset -- HEAD");
+    let status = run_libra_command(&["status", "--short"], repo.path());
+    assert_cli_success(&status, "status --short");
+    assert_eq!(String::from_utf8_lossy(&status.stdout), " M HEAD\n");
+}
+
+#[test]
+fn reset_bare_revision_path_ambiguity_errors_like_git() {
+    // Given: a token names both a branch and a tracked path.
+    let repo = create_committed_repo_via_cli();
+    fs::write(repo.path().join("feature"), "branch/path collision\n").unwrap();
+    let add = run_libra_command(&["add", "feature"], repo.path());
+    assert_cli_success(&add, "add feature file");
+    let commit = run_libra_command(
+        &["commit", "-m", "add feature file", "--no-verify"],
+        repo.path(),
+    );
+    assert_cli_success(&commit, "commit feature file");
+    let branch = run_libra_command(&["branch", "feature"], repo.path());
+    assert_cli_success(&branch, "create feature branch");
+    fs::write(
+        repo.path().join("feature"),
+        "branch/path collision\nupdated\n",
+    )
+    .unwrap();
+    let add = run_libra_command(&["add", "feature"], repo.path());
+    assert_cli_success(&add, "stage feature file update");
+
+    // When: reset receives the ambiguous token without `--`.
+    let output = run_libra_command(&["reset", "feature"], repo.path());
+    let (stderr, report) = parse_cli_error_stderr(&output.stderr);
+
+    // Then: it refuses to guess between revision and pathspec.
+    assert_eq!(output.status.code(), Some(129));
+    assert_eq!(report.error_code, "LBR-CLI-002");
+    assert!(
+        stderr.contains("ambiguous argument 'feature': both revision and filename"),
+        "unexpected stderr: {stderr}"
+    );
+    let status = run_libra_command(&["status", "--short"], repo.path());
+    assert_cli_success(&status, "status --short");
+    assert_eq!(String::from_utf8_lossy(&status.stdout), "M  feature\n");
+}
+
 #[test]
 fn test_reset_json_hard_with_pathspec_returns_usage_error() {
     let repo = create_committed_repo_via_cli();
@@ -573,11 +655,12 @@ async fn test_reset_hard_io_failure_rolls_back_index_and_keeps_head() {
 
     let result = reset::execute_safe(
         ResetArgs {
-            target: "HEAD~1".to_string(),
+            target: Some("HEAD~1".to_string()),
             soft: false,
             mixed: false,
             hard: true,
             pathspecs: vec![],
+            pathspec_separator: false,
             pathspec_from_file: None,
             pathspec_file_nul: false,
             no_refresh: false,
@@ -911,11 +994,12 @@ async fn test_reset_soft() {
 
     // Perform soft reset to commit 1
     reset::execute(ResetArgs {
-        target: "1".to_string(), // Reset to branch 1
+        target: Some("1".to_string()), // Reset to branch 1
         soft: true,
         mixed: false,
         hard: false,
         pathspecs: vec![],
+        pathspec_separator: false,
         pathspec_from_file: None,
         pathspec_file_nul: false,
         no_refresh: false,
@@ -958,11 +1042,12 @@ async fn test_reset_mixed() {
 
     // Perform mixed reset (default) to commit 1
     reset::execute(ResetArgs {
-        target: "1".to_string(), // Reset to branch 1
+        target: Some("1".to_string()), // Reset to branch 1
         soft: false,
         mixed: false, // false means default (mixed)
         hard: false,
         pathspecs: vec![],
+        pathspec_separator: false,
         pathspec_from_file: None,
         pathspec_file_nul: false,
         no_refresh: false,
@@ -1009,11 +1094,12 @@ async fn test_reset_hard() {
 
     // Perform hard reset to commit 1
     reset::execute(ResetArgs {
-        target: "1".to_string(), // Reset to branch 1
+        target: Some("1".to_string()), // Reset to branch 1
         soft: false,
         mixed: false,
         hard: true,
         pathspecs: vec![],
+        pathspec_separator: false,
         pathspec_from_file: None,
         pathspec_file_nul: false,
         no_refresh: false,
@@ -1130,11 +1216,12 @@ async fn test_reset_mixed_same_target_resets_index_without_moving_head() {
 
     reset::execute_safe(
         ResetArgs {
-            target: "HEAD".to_string(),
+            target: Some("HEAD".to_string()),
             soft: false,
             mixed: true,
             hard: false,
             pathspecs: vec![],
+            pathspec_separator: false,
             pathspec_from_file: None,
             pathspec_file_nul: false,
             no_refresh: false,
@@ -1223,11 +1310,12 @@ async fn test_reset_hard_same_target_restores_worktree_and_removes_staged_additi
 
     reset::execute_safe(
         ResetArgs {
-            target: "HEAD".to_string(),
+            target: Some("HEAD".to_string()),
             soft: false,
             mixed: false,
             hard: true,
             pathspecs: vec![],
+            pathspec_separator: false,
             pathspec_from_file: None,
             pathspec_file_nul: false,
             no_refresh: false,
@@ -1349,11 +1437,12 @@ async fn test_reset_hard_removes_paths_tracked_only_by_head_tree() {
 
     reset::execute_safe(
         ResetArgs {
-            target: "HEAD~1".to_string(),
+            target: Some("HEAD~1".to_string()),
             soft: false,
             mixed: false,
             hard: true,
             pathspecs: vec![],
+            pathspec_separator: false,
             pathspec_from_file: None,
             pathspec_file_nul: false,
             no_refresh: false,
@@ -1390,11 +1479,12 @@ async fn test_reset_with_head_reference() {
 
     // Reset using HEAD~ syntax
     reset::execute(ResetArgs {
-        target: "HEAD~1".to_string(),
+        target: Some("HEAD~1".to_string()),
         soft: false,
         mixed: true,
         hard: false,
         pathspecs: vec![],
+        pathspec_separator: false,
         pathspec_from_file: None,
         pathspec_file_nul: false,
         no_refresh: false,
@@ -1436,11 +1526,12 @@ async fn test_reset_on_branch() {
 
             // Perform reset
             reset::execute(ResetArgs {
-                target: commit1.to_string(),
+                target: Some(commit1.to_string()),
                 soft: true,
                 mixed: false,
                 hard: false,
                 pathspecs: vec![],
+                pathspec_separator: false,
                 pathspec_from_file: None,
                 pathspec_file_nul: false,
                 no_refresh: false,
@@ -1525,11 +1616,12 @@ async fn test_reset_hard_skips_ignored_directories() {
 
     // Perform hard reset
     reset::execute(ResetArgs {
-        target: "HEAD".to_string(),
+        target: Some("HEAD".to_string()),
         soft: false,
         mixed: false,
         hard: true,
         pathspecs: vec![],
+        pathspec_separator: false,
         pathspec_from_file: None,
         pathspec_file_nul: false,
         no_refresh: false,

From 7b6660a62a7db2c76e03aa829e1804513e6cb0f5 Mon Sep 17 00:00:00 2001
From: Quanyi Ma <eli@patch.sh>
Date: Mon, 6 Jul 2026 22:21:26 +0800
Subject: [PATCH 2/4] fix(reset): address review and self-runner test failures
 (#432)

* test(cloud): isolate restore object tests from cwd

Signed-off-by: Quanyi Ma <eli@patch.sh>

* fix(reset): preserve separator for dash-prefixed paths

Signed-off-by: Quanyi Ma <eli@patch.sh>

* test(file): avoid sqlite3 binary in obliterate recovery

Signed-off-by: Quanyi Ma <eli@patch.sh>

---------

Signed-off-by: Quanyi Ma <eli@patch.sh>
---
 src/cli.rs                            |  1 +
 src/command/cloud.rs                  | 20 ++++++++++
 tests/command/file_obliterate_test.rs | 56 ++++++++++++++++++++-------
 tests/command/reset_test.rs           | 35 +++++++++++++++++
 4 files changed, 99 insertions(+), 13 deletions(-)

diff --git a/src/cli.rs b/src/cli.rs
index 6ccf3982a..5c6c2034c 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1066,6 +1066,7 @@ fn rewrite_reset_pathspec_separator_args(args: Vec<String>) -> Vec<String> {
     if !has_target_before_separator && args.get(separator_index + 1).is_some() {
         out.push("HEAD".to_string());
     }
+    out.push("--".to_string());
     out.extend(args.iter().skip(separator_index + 1).cloned());
     out
 }
diff --git a/src/command/cloud.rs b/src/command/cloud.rs
index 9004ca8cb..f93f8a126 100644
--- a/src/command/cloud.rs
+++ b/src/command/cloud.rs
@@ -2504,6 +2504,22 @@ mod tests {
         }
     }
 
+    async fn enter_isolated_libra_repo() -> (
+        tempfile::TempDir,
+        tempfile::TempDir,
+        ScopedEnvVar,
+        ScopedEnvVar,
+        ChangeDirGuard,
+    ) {
+        let repo = tempdir().unwrap();
+        let home = tempdir().unwrap();
+        let home_env = ScopedEnvVar::set("HOME", home.path());
+        let test_home_env = ScopedEnvVar::set("LIBRA_TEST_HOME", home.path());
+        setup_with_new_libra_in(repo.path()).await;
+        let cwd = ChangeDirGuard::new(repo.path());
+        (repo, home, home_env, test_home_env, cwd)
+    }
+
     struct ClearedEnvVarGuard {
         key: String,
         previous: Option<OsString>,
@@ -2882,7 +2898,9 @@ mod tests {
     }
 
     #[tokio::test]
+    #[serial]
     async fn cloud_restore_indexed_objects_downloads_skips_and_verifies_hash() {
+        let _repo = enter_isolated_libra_repo().await;
         let remote = RemoteStorage::new(Arc::new(InMemory::new()));
         let local_dir = tempdir().unwrap();
         let local = LocalStorage::new(local_dir.path().to_path_buf());
@@ -2917,7 +2935,9 @@ mod tests {
     }
 
     #[tokio::test]
+    #[serial]
     async fn cloud_restore_indexed_objects_reports_hash_mismatch() {
+        let _repo = enter_isolated_libra_repo().await;
         let remote = RemoteStorage::new(Arc::new(InMemory::new()));
         let local_dir = tempdir().unwrap();
         let local = LocalStorage::new(local_dir.path().to_path_buf());
diff --git a/tests/command/file_obliterate_test.rs b/tests/command/file_obliterate_test.rs
index 1b61b20ea..1987ea017 100644
--- a/tests/command/file_obliterate_test.rs
+++ b/tests/command/file_obliterate_test.rs
@@ -6,7 +6,13 @@
 //!
 //! Layer: L1 (deterministic; tempdir + isolated HOME, no network).
 
-use std::fs;
+use std::{
+    fs,
+    path::{Path, PathBuf},
+    time::Duration,
+};
+
+use sea_orm::{ConnectOptions, ConnectionTrait, Database, DatabaseConnection, Statement};
 
 use super::{
     assert_cli_success, create_committed_repo_via_cli, parse_cli_error_stderr, run_libra_command,
@@ -36,10 +42,42 @@ fn repo_with_secret() -> (tempfile::TempDir, String) {
     (repo, oid)
 }
 
-fn loose_path(repo: &std::path::Path, oid: &str) -> std::path::PathBuf {
+fn loose_path(repo: &Path, oid: &str) -> PathBuf {
     repo.join(".libra/objects").join(&oid[..2]).join(&oid[2..])
 }
 
+async fn connect_raw_repo_db(repo: &Path) -> DatabaseConnection {
+    let db_path = repo.join(".libra").join("libra.db");
+    let mut opts = ConnectOptions::new(format!("sqlite://{}", db_path.display()));
+    opts.sqlx_logging(false)
+        .connect_timeout(Duration::from_secs(5));
+    Database::connect(opts)
+        .await
+        .expect("connect raw repository database")
+}
+
+fn mark_obliteration_as_interrupted(repo: &Path) {
+    let runtime = tokio::runtime::Runtime::new().expect("create runtime for crash-recovery setup");
+    runtime.block_on(async {
+        let conn = connect_raw_repo_db(repo).await;
+        let result = conn
+            .execute(Statement::from_string(
+                conn.get_database_backend(),
+                "UPDATE object_obliteration SET state='obliterating', payload_deleted_at=NULL",
+            ))
+            .await
+            .expect("reset obliteration state to 'obliterating'");
+        assert_eq!(
+            result.rows_affected(),
+            1,
+            "reset exactly one obliteration row to 'obliterating'"
+        );
+        conn.close()
+            .await
+            .expect("close crash-recovery setup database");
+    });
+}
+
 #[test]
 fn obliterate_dry_run_previews_and_deletes_nothing() {
     let (repo, oid) = repo_with_secret();
@@ -148,17 +186,9 @@ fn obliterate_recover_finishes_interrupted() {
         "payload restored on disk for the test"
     );
 
-    // Force the mid-state via sqlite3 — REQUIRED (fail, don't skip, if absent).
-    let db = p.join(".libra/libra.db");
-    let status = std::process::Command::new("sqlite3")
-        .arg(&db)
-        .arg("UPDATE object_obliteration SET state='obliterating', payload_deleted_at=NULL;")
-        .status()
-        .expect("sqlite3 is required for the crash-recovery test");
-    assert!(
-        status.success(),
-        "reset the obliteration state to 'obliterating'"
-    );
+    // Force the mid-state in the repository database without relying on host
+    // sqlite3 binaries, which are not guaranteed on self-hosted runners.
+    mark_obliteration_as_interrupted(p);
 
     // Recovery must re-delete the payload and finalize.
     let recover = run_libra_command(&["file", "obliterate", "--recover"], p);
diff --git a/tests/command/reset_test.rs b/tests/command/reset_test.rs
index 96893997a..9cf6550b9 100644
--- a/tests/command/reset_test.rs
+++ b/tests/command/reset_test.rs
@@ -372,6 +372,41 @@ fn reset_double_dash_pathspec_unstages_file_named_like_revision() {
     assert_eq!(String::from_utf8_lossy(&status.stdout), " M HEAD\n");
 }
 
+#[test]
+fn reset_double_dash_preserves_dash_prefixed_pathspecs() {
+    // Given: tracked files have names that would otherwise parse as flags.
+    let repo = create_committed_repo_via_cli();
+    for name in ["-h", "--help"] {
+        fs::write(repo.path().join(name), format!("{name}\n")).unwrap();
+        let add = run_libra_command(&["add", "--", name], repo.path());
+        assert_cli_success(&add, "add dash-prefixed file");
+    }
+    let commit = run_libra_command(
+        &["commit", "-m", "add dash-prefixed files", "--no-verify"],
+        repo.path(),
+    );
+    assert_cli_success(&commit, "commit dash-prefixed files");
+
+    for name in ["-h", "--help"] {
+        fs::write(repo.path().join(name), format!("{name}\nupdated\n")).unwrap();
+        let add = run_libra_command(&["add", "--", name], repo.path());
+        assert_cli_success(&add, "stage dash-prefixed file update");
+
+        // When: `--` marks the dash-prefixed token as a pathspec.
+        let output = run_libra_command(&["reset", "--", name], repo.path());
+
+        // Then: reset treats the token as a filename instead of a reset/help flag.
+        assert_cli_success(&output, "reset dash-prefixed pathspec");
+        let status = run_libra_command(&["status", "--short"], repo.path());
+        assert_cli_success(&status, "status --short");
+        let stdout = String::from_utf8_lossy(&status.stdout);
+        assert!(
+            stdout.contains(&format!(" M {name}\n")),
+            "expected {name} to be unstaged, got: {stdout}",
+        );
+    }
+}
+
 #[test]
 fn reset_bare_revision_path_ambiguity_errors_like_git() {
     // Given: a token names both a branch and a tracked path.

From c226ee76370c77d3562af9a99eb1a8ac88efe151 Mon Sep 17 00:00:00 2001
From: Quanyi Ma <eli@patch.sh>
Date: Mon, 6 Jul 2026 23:01:24 +0800
Subject: [PATCH 3/4] fix(reset): tighten reset target disambiguation

Signed-off-by: Quanyi Ma <eli@patch.sh>
---
 src/cli.rs                  |  2 +-
 src/command/reset.rs        | 33 ++++++++++++++++++++-------------
 tests/command/reset_test.rs | 17 +++++++++++++++++
 3 files changed, 38 insertions(+), 14 deletions(-)

diff --git a/src/cli.rs b/src/cli.rs
index 5c6c2034c..c34d308be 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1064,7 +1064,7 @@ fn rewrite_reset_pathspec_separator_args(args: Vec<String>) -> Vec<String> {
         command::reset::RESET_PATHSPEC_SEPARATOR_FLAG
     ));
     if !has_target_before_separator && args.get(separator_index + 1).is_some() {
-        out.push("HEAD".to_string());
+        out.push(command::reset::DEFAULT_RESET_TARGET.to_string());
     }
     out.push("--".to_string());
     out.extend(args.iter().skip(separator_index + 1).cloned());
diff --git a/src/command/reset.rs b/src/command/reset.rs
index 9765aebf0..92d197915 100644
--- a/src/command/reset.rs
+++ b/src/command/reset.rs
@@ -50,7 +50,7 @@ EXAMPLES:
     libra reset --json --hard HEAD~1      Structured JSON output for agents";
 
 pub(crate) const RESET_PATHSPEC_SEPARATOR_FLAG: &str = "__libra-reset-pathspec-separator";
-const DEFAULT_RESET_TARGET: &str = "HEAD";
+pub(crate) const DEFAULT_RESET_TARGET: &str = "HEAD";
 
 #[derive(Parser, Debug)]
 #[command(after_help = RESET_EXAMPLES)]
@@ -511,20 +511,22 @@ async fn normalize_reset_request(args: &ResetArgs) -> Result<ResetRequest, Reset
         return Ok(ResetRequest { target, pathspecs });
     };
     let resolves_as_revision = target_resolves_as_revision(target_arg).await?;
-    let matches_path = pathspec_matches_known_path(target_arg).await?;
-
-    match (resolves_as_revision, matches_path) {
-        (true, true) => Err(ResetError::AmbiguousRevisionPath(target_arg.to_string())),
-        (true, false) => Ok(ResetRequest { target, pathspecs }),
-        (false, true) => {
-            pathspecs.insert(0, target_arg.to_string());
-            Ok(ResetRequest {
-                target: DEFAULT_RESET_TARGET.to_string(),
-                pathspecs,
-            })
+    if resolves_as_revision {
+        if pathspec_exists_in_worktree(target_arg) {
+            return Err(ResetError::AmbiguousRevisionPath(target_arg.to_string()));
         }
-        (false, false) => Ok(ResetRequest { target, pathspecs }),
+        return Ok(ResetRequest { target, pathspecs });
+    }
+
+    if pathspec_matches_known_path(target_arg).await? {
+        pathspecs.insert(0, target_arg.to_string());
+        return Ok(ResetRequest {
+            target: DEFAULT_RESET_TARGET.to_string(),
+            pathspecs,
+        });
     }
+
+    Ok(ResetRequest { target, pathspecs })
 }
 
 async fn target_resolves_as_revision(target: &str) -> Result<bool, ResetError> {
@@ -567,6 +569,11 @@ async fn pathspec_matches_known_path(pathspec: &str) -> Result<bool, ResetError>
     find_tree_item(&tree, path_str).map(|item| item.is_some())
 }
 
+fn pathspec_exists_in_worktree(pathspec: &str) -> bool {
+    let absolute = util::workdir_to_absolute(PathBuf::from(pathspec));
+    absolute.exists() && util::is_sub_path(&absolute, util::working_dir())
+}
+
 /// Reset specific files in the index to their state in the target commit.
 /// This function only affects the index, not the working directory.
 async fn reset_pathspecs(
diff --git a/tests/command/reset_test.rs b/tests/command/reset_test.rs
index 9cf6550b9..13dba2287 100644
--- a/tests/command/reset_test.rs
+++ b/tests/command/reset_test.rs
@@ -445,6 +445,23 @@ fn reset_bare_revision_path_ambiguity_errors_like_git() {
     assert_eq!(String::from_utf8_lossy(&status.stdout), "M  feature\n");
 }
 
+#[test]
+fn reset_soft_revision_does_not_probe_index_for_pathspec_disambiguation() {
+    // Given: a normal repository whose index is unreadable.
+    let repo = create_committed_repo_via_cli();
+    fs::write(
+        repo.path().join(".libra").join("index"),
+        b"corrupted-index-data",
+    )
+    .unwrap();
+
+    // When: reset receives an unambiguous revision target.
+    let output = run_libra_command(&["reset", "--soft", "HEAD"], repo.path());
+
+    // Then: soft reset resolves the revision without probing pathspec state.
+    assert_cli_success(&output, "reset --soft HEAD with corrupt index");
+}
+
 #[test]
 fn test_reset_json_hard_with_pathspec_returns_usage_error() {
     let repo = create_committed_repo_via_cli();

From 30fa1c2f5a742413b27d8a8da2b943e2c80059ac Mon Sep 17 00:00:00 2001
From: Quanyi Ma <eli@patch.sh>
Date: Tue, 7 Jul 2026 01:11:12 +0800
Subject: [PATCH 4/4] test(network): refresh public GitHub fixture

---
 tests/network_remotes_test.rs | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/tests/network_remotes_test.rs b/tests/network_remotes_test.rs
index b738442b7..60cea353a 100644
--- a/tests/network_remotes_test.rs
+++ b/tests/network_remotes_test.rs
@@ -13,10 +13,12 @@ use libra::{
 };
 use url::Url;
 
+const PUBLIC_FIXTURE_REPO: &str = "https://github.com/libra-tools/libra.git";
+const PUBLIC_FIXTURE_REPO_WEB_URL: &str = "https://github.com/libra-tools/libra/";
+
 #[tokio::test]
 async fn https_discovery_upload_pack_lists_refs() {
-    let client =
-        HttpsClient::from_url(&Url::parse("https://github.com/libra-tools/mega.git/").unwrap());
+    let client = HttpsClient::from_url(&Url::parse(PUBLIC_FIXTURE_REPO).unwrap());
     let discovery = client
         .discovery_reference(UploadPack)
         .await
@@ -34,8 +36,7 @@ async fn https_discovery_upload_pack_lists_refs() {
 
 #[tokio::test]
 async fn https_upload_pack_returns_pack_data() {
-    let client =
-        HttpsClient::from_url(&Url::parse("https://github.com/libra-tools/mega/").unwrap());
+    let client = HttpsClient::from_url(&Url::parse(PUBLIC_FIXTURE_REPO_WEB_URL).unwrap());
     let discovery = client
         .discovery_reference(UploadPack)
         .await
@@ -77,8 +78,7 @@ async fn github_lfs_batch_download_returns_response() {
         }],
         hash_algo: lfs::LFS_HASH_ALGO.to_string(),
     };
-    let lfs_client =
-        LFSClient::from_url(&Url::parse("https://github.com/libra-tools/mega.git").unwrap());
+    let lfs_client = LFSClient::from_url(&Url::parse(PUBLIC_FIXTURE_REPO).unwrap());
     let response = lfs_client
         .client
         .post(lfs_client.batch_url.clone())