paseokit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

paseokit

Paseo shows one workspace per checkout, either a main repo or a git worktree under it, and hangs agents off each one. Worktrees themselves come from plain

git worktree

: gitkit's convention, issuekit's

start

, or your own hands.

Paseo's registry is explicit-only in both directions. A worktree that

git worktree add

created is invisible to Paseo until something registers it, and a workspace whose directory was deleted stays in the sidebar forever. There is no discovery setting to turn on and no prune command to run. So the sidebar drifts from the disk in both directions at once: real work that never appears, and finished work that never leaves.

paseokit owns exactly that reconciliation: Paseo's registry, made to match the worktrees that actually exist. One command, machine-wide, and running it twice changes nothing the second time.

It is on-demand by design. Worktrees appear in Paseo when you run

sync

, not when they are created. That is a deliberate trade: no git hooks, no scheduler, no background process, nothing written into any repo.

Paseo 为每个检出项显示一个workspace，无论是主仓库还是其下的git worktree，并为每个workspace关联agents。工作区本身来自原生的

git worktree

：gitkit 的约定、issuekit 的

start

命令，或是你手动创建的。

**Paseo 的注册表在双向操作上均为显式模式。**通过

git worktree add

创建的工作区在被注册前对 Paseo 是不可见的，而目录已被删除的工作区会永远留在侧边栏中。这里没有可开启的发现设置，也没有可执行的清理命令。因此侧边栏会与磁盘状态双向脱节：真实存在的工作区从未显示，已完成的工作区却始终存在。

paseokit 专门负责这种一致性维护：让 Paseo 的注册表与实际存在的工作区保持一致。只需一条命令即可在全机生效，重复执行第二次不会产生任何变化。

它设计为按需触发。工作区只会在你执行

sync

时才会出现在 Paseo 中，而不是在创建时就自动同步。这是一种刻意的取舍：无需 git 钩子、调度器或后台进程，也不会向任何仓库写入内容。

The line paseokit does not cross

paseokit 不会跨越的边界

Git owns the worktree; Paseo owns the row. paseokit never runs

paseo workspace create --isolation worktree

to do real work, never invents a path, and never lets Paseo create a branch. Creating and removing a worktree is native

git worktree

under gitkit's convention, so a machine with no Paseo on it runs identical commands.

paseokit works one layer up, on the only thing Paseo alone knows: the registry row, meaning that a workspace exists for this path, under this project, with this title.

Two consequences worth stating plainly:

paseo workspace archive
is registry-only. It removes the row and leaves the directory, the branch, and git's own worktree registration completely intact. That is what lets
```
sync
```
reap without a destructive-confirm gate, because nothing it does can lose work.
Removing a worktree is still gitkit's job. Paseo does not notice a deleted directory, so the row has to be archived afterward, which is precisely what
```
sync
```
is for.

paseokit never touches the tracker. It reads issues and pull requests to build a title and judge a verdict; it never closes an issue, moves a label, or edits a pull request. A merged pull request whose issue is still open is tracker drift, and it says so, routing to issuekit

close

Git 管理工作区；Paseo 管理条目。 paseokit 绝不会执行

paseo workspace create --isolation worktree

来创建实际工作区，不会凭空生成路径，也不会让 Paseo 创建分支。创建和删除工作区是遵循 gitkit 约定的原生

git worktree

操作，因此即使机器上没有 Paseo，也能执行完全相同的命令。

paseokit 工作在更高一层，仅处理只有 Paseo 知晓的内容：注册表条目，即某个路径下存在一个工作区，隶属于某个项目，并拥有特定标题。

有两个结果需要明确说明：

**
```
paseo workspace archive
```
仅针对注册表。**它只会删除条目，而目录、分支以及 Git 自身的工作区注册信息会完全保留。这也是
```
sync
```
无需确认即可清理的原因——它的任何操作都不会导致工作内容丢失。
删除工作区仍是 gitkit 的职责。 Paseo 不会察觉到目录已被删除，因此条目必须在删除后进行归档，而这正是
```
sync
```
的作用所在。

**paseokit 绝不会触及跟踪系统。**它会读取议题和拉取请求来生成标题并判断状态，但绝不会关闭议题、移动标签或编辑拉取请求。已合并的拉取请求对应的议题仍处于打开状态属于跟踪系统的脱节情况，此时会提示用户使用 issuekit 的

close

命令处理。

When this fires

触发场景

list
. "What does paseo think my worktrees are", "why isn't my worktree in the sidebar", "show me the drift". Read-only.
sync
. "Sync my worktrees to paseo", "register my worktrees", "clean the dead rows out of my sidebar".
align
. "Where should paseo put new worktrees", "make paseo use my worktree root".

If no mode is clear, start with
list
. It is read-only and it names which rows

sync

would touch, so it is never the wrong first move.

Not this skill: creating or removing a worktree (gitkit), closing an issue and tearing down after a merge (issuekit

close

), or driving agents, since

paseo run

attach

send

logs

, and the schedule surface all belong to the

paseo

CLI directly. paseokit is registry hygiene, not agent operation.

list
模式：“paseo 认为我的工作区有哪些”、“为什么我的工作区不在侧边栏中”、“显示状态差异”。只读模式。
sync
模式：“将我的工作区同步到 paseo”、“注册我的工作区”、“清理侧边栏中的无效条目”。
align
模式：“paseo 应该把新工作区放在哪里”、“让 paseo 使用我的工作区根目录”。

**如果不清楚该使用哪种模式，先从

list

开始。**它是只读模式，会列出

sync

会处理的条目，因此永远不会是错误的第一步。

不属于该工具的操作：创建或删除工作区（gitkit 的职责）、关闭议题并在合并后清理（issuekit 的

close

命令）、或是管理 agents——因为

paseo run

、

attach

、

send

、

logs

以及调度功能都属于

paseo

CLI 的直接操作范围。paseokit 负责注册表的维护，而非 agent 的操作。

Preflight (every mode)

预检（所有模式通用）

paseo status        # CLI installed? daemon running and reachable?

paseo
not installed → this machine has no Paseo, so there is nothing to reconcile. Say exactly that and stop. Do not fall back to anything: the worktrees are already fine without Paseo, and nothing else in the workflow depends on this skill.
Daemon not running or unreachable → name
```
paseo start
```
and stop. Do not start a daemon on someone's machine unasked.
gh
missing or unauthenticated → titles degrade to the branch name and the tracker column reads "unknown". Nothing else degrades. Unlike a worktree-deleting sweep, no operation here is gated on proving a merge, so a missing
```
gh
```
never blocks a mode.
A rejected
paseo
flag or subcommand → the CLI moves fast. Check
```
paseo <command> --help
```
before concluding an operation is unsupported. The goal is the contract, meaning the row registered, the row archived, the title set; the exact flag spelling is not.

Verified against Paseo 0.4.0, CLI and daemon. Re-check the seam below against a newer version before trusting a write.

paseo status        # CLI 是否已安装？守护进程是否正在运行且可访问？

未安装
paseo
→ 该机器上没有 Paseo，无需进行一致性维护。直接告知用户并停止操作。不要回退到其他操作：没有 Paseo 时工作区本身已经正常，且工作流中的其他环节不依赖该工具。
守护进程未运行或无法访问 → 告知用户执行
```
paseo start
```
并停止操作。不要未经用户同意就启动守护进程。
缺少
gh
或未认证 → 标题会降级为分支名称，跟踪系统列显示为“未知”。其他功能不受影响。与删除工作区的操作不同，此处的任何操作都无需验证合并状态，因此缺少
```
gh
```
不会阻塞任何模式的执行。
paseo
标志或子命令被拒绝 → CLI 更新速度较快。在判定操作不支持前，请先查看
```
paseo <command> --help
```
。目标是完成合约，即完成条目注册、归档、标题设置；具体的标志拼写并不重要。

已针对 Paseo 0.4.0 版本的 CLI 和守护进程进行验证。在信任写入操作前，请针对新版本重新检查以下内容。

What Paseo knows about a workspace

Paseo 对工作区的认知

Two surfaces, and the difference between them is load-bearing.

The CLI listing is a thin projection.

paseo workspace ls --json

returns only

workspaceId

project

(the display name, not the id),

name

isolation

, and

cwd

. It lists active workspaces only. That is enough to answer one question, which is whether any live row points at this path, and nothing else.

The state files carry the rest. Everything the modes below actually decide on lives in two JSON files under

~/.paseo/projects/

file	what it uniquely provides	needed for
`projects.json`	`projectId` per `rootPath` , plus `projectKey` and `archivedAt`	every registration, since `--project` is mandatory
`workspaces.json`	`branch` , `title` , `projectId` , `createdAt` , `archivedAt`	tombstones, duplicate ordering, retitle safety

This is a documented seam, not a stable API. Paseo 0.4.0 ships no

project ls

--project

rejects both a name and a path, and the

prj_…

id is not derivable from

projectKey

by any hash, so reading the files is unavoidable rather than a shortcut. Treat them as read-only: paseokit parses them and writes through the CLI, never into them.

If either file is missing, unreadable, or shaped unexpectedly, degrade every writing mode to read-only and say which file and why. Never guess at an id.

A workspace carries a title and a pin, and nothing else, with no issue link and no status field. So

link

-style enrichment has no equivalent here; the title is the entire surface.

有两个层面的信息，它们之间的差异至关重要。

CLI 列表是一个精简的投影。

paseo workspace ls --json

仅返回

workspaceId

、

project

（显示名称而非 ID）、

name

、

isolation

和

cwd

。它仅列出活跃的工作区。这足以回答一个问题：是否有任何活跃条目指向该路径，仅此而已。

**状态文件包含其余信息。**以下模式中实际需要决定的所有内容都存储在

~/.paseo/projects/

下的两个 JSON 文件中：

文件	唯一提供的内容	用途
`projects.json`	每个 `rootPath` 对应的 `projectId` ，以及 `projectKey` 和 `archivedAt`	所有注册操作，因为 `--project` 是必填项
`workspaces.json`	`branch` 、 `title` 、 `projectId` 、 `createdAt` 、 `archivedAt`	已归档条目、重复项排序、标题修改安全性

这是一个已公开的衔接点，而非稳定 API。 Paseo 0.4.0 没有提供

project ls

命令，

--project

既不接受名称也不接受路径，且

prj_…

格式的 ID 无法通过任何哈希从

projectKey

推导出来，因此读取这些文件是不可避免的，而非捷径。请将它们视为只读：paseokit 仅解析这些文件，并通过 CLI 写入，绝不会直接修改它们。

如果任一文件缺失、无法读取或格式不符合预期，将所有写入模式降级为只读，并告知用户具体是哪个文件以及原因。切勿猜测 ID。

工作区包含标题和固定标记，无其他内容，没有议题链接或状态字段。因此此处没有类似

link

样式的增强功能；标题是唯一的展示内容。

Two things the registry gets wrong

注册表存在的两个问题

isPaseoOwnedWorktree
is a known lie. Paseo sets it
```
true
```
for a worktree that git created and Paseo merely adopted. No CLI corrects it, so the desktop app may offer to delete a worktree that git owns. paseokit documents this and works around nothing; it never reads the flag to make a decision.
workspace create
is not idempotent. Two identical calls on one path silently produce two rows with the same
```
cwd
```
. Every existence check before a registration is therefore load-bearing rather than an optimization, and it must consider archived rows too, or the tombstone rule below fails silently.

isPaseoOwnedWorktree
是已知的错误标记。 Paseo 会将 Git 创建、Paseo 仅接管的工作区标记为
```
true
```
。没有 CLI 可以纠正这个标记，因此桌面应用可能会提供删除 Git 所属工作区的选项。paseokit 会记录这个问题，但不会进行任何处理；它绝不会读取该标记来做出决策。
workspace create
不是幂等的。对同一路径执行两次相同的调用会静默生成两个具有相同
cwd
的条目。因此注册前的存在性检查至关重要，而非优化手段，且必须考虑已归档的条目，否则下面的已归档条目规则会静默失效。

Mode:

list

模式：

list

Read-only. Changes nothing, asks nothing, and is the right first move whenever the state is unclear.

Join three sources and match on absolute path, the only key both git and Paseo record:

git -C "$REPO" worktree list --porcelain    # per live project in projects.json
paseo workspace ls --json                   # active rows
paseo ls --json                             # agents, each with a cwd and a status

Two filters before anything gets a verdict:

No symbolic HEAD, no row. A porcelain record carries either
```
branch refs/heads/<name>
```
or
```
detached
```
; the detached ones never register. This is the same answer
```
git symbolic-ref -q HEAD
```
gives inside the worktree, and it is what keeps debugkit's bisect scratch out of the sidebar.
Agent
cwd
values come back tilde-abbreviated (
```
~/projects/skills
```
). Expand before comparing, or every
```
busy
```
check quietly returns false.

Then give every row a verdict:

verdict	means	fix
`busy`	a non-idle agent's `cwd` is inside this workspace	leave it
`registered`	worktree exists, exactly one active row points at it	nothing
`unregistered`	worktree exists, no row points at it	`sync`
`orphaned`	an active row points at a path that no longer exists	`sync`
`duplicate`	two or more active rows share one `cwd`	`sync`
`tombstoned`	worktree exists, and its only row is archived	`sync` , on confirmation
`unknown repo`	worktree under `$WORKTREE_ROOT` whose repo Paseo has never seen	`sync` , on confirmation
`stray project`	a project whose `rootPath` is a worktree rather than a main checkout	reported only; no CLI deletes a project
`reapable`	pull request merged, issue closed, tree clean	gitkit teardown, then `sync`

Put
busy
rows first when any exist. Those are the rows where an action would interrupt live work.

A stray project has a clear signature: its

projectKey

matches a real project's while its

rootPath

sits under

$WORKTREE_ROOT

. That is what a registration without

--project

produces, and it is invisible in

workspace ls

because the row beneath it may since have been archived.

只读模式。不会更改任何内容，也不会询问任何问题，当状态不明确时，这是正确的第一步。

关联三个数据源，并通过绝对路径进行匹配——这是 Git 和 Paseo 都会记录的唯一键：

git -C "$REPO" worktree list --porcelain    # 对应 projects.json 中的每个活跃项目
paseo workspace ls --json                   # 活跃条目
paseo ls --json                             # agents，每个都包含 cwd 和状态

在给出判定前，先应用两个过滤器：

无符号 HEAD，无条目。 porcelain 记录会包含
```
branch refs/heads/<name>
```
或
```
detached
```
；处于 detached 状态的工作区永远不会被注册。这与在工作区内执行
```
git symbolic-ref -q HEAD
```
的结果一致，可避免 debugkit 的二分查找临时工作区出现在侧边栏中。
Agent 的
cwd
值会以波浪号缩写（如
```
~/projects/skills
```
）。在比较前请展开路径，否则所有“忙碌”检查都会静默返回 false。

然后为每个条目给出判定：

判定结果	含义	修复方式
`busy`	非空闲 agent 的 `cwd` 位于该工作区内	保留
`registered`	工作区存在，且恰好有一个活跃条目指向它	无需操作
`unregistered`	工作区存在，但没有条目指向它	`sync`
`orphaned`	活跃条目指向的路径已不存在	`sync`
`duplicate`	两个或多个活跃条目共享同一个 `cwd`	`sync`
`tombstoned`	工作区存在，但唯一的条目已归档	`sync` ，需确认
`unknown repo`	`$WORKTREE_ROOT` 下的工作区，其仓库从未被 Paseo 识别	`sync` ，需确认
`stray project`	项目的 `rootPath` 是工作区而非主检出项	仅报告；没有 CLI 可以删除项目
`reapable`	拉取请求已合并，议题已关闭，工作区已清理	gitkit 清理，然后执行 `sync`

**如果存在

busy

条目，请优先显示它们。**这些条目对应的操作会中断正在进行的工作。

游离项目有明确的特征：其

projectKey

与真实项目匹配，但

rootPath

位于

$WORKTREE_ROOT

下。这是未指定

--project

参数的注册操作导致的，且在

workspace ls

中不可见，因为其下的条目可能已被归档。

Hand off

后续操作

Write every hand-off in this skill in the procedural register: one instruction per sentence, active voice, present tense, no metaphor.

What changed. Nothing. Say so.

Where it landed. Give one table, with the counts per verdict.

Next. Crown

sync

when any row is

unregistered

orphaned

duplicate

, or

tombstoned

. Crown gitkit teardown instead when the only findings are

reapable

. Say plainly that the sidebar already matches the disk when every row reads

registered

本工具中的所有后续操作说明均采用过程式表述：每句一条指令，主动语态，现在时态，无隐喻。

变更内容：无任何变更。直接告知用户。

当前状态：提供一个表格，按判定结果统计数量。

下一步：如果存在

unregistered

、

orphaned

、

duplicate

或

tombstoned

条目，推荐执行

sync

。如果仅发现

reapable

条目，则推荐执行 gitkit 清理操作。如果所有条目均为

registered

，则明确告知用户侧边栏已与磁盘状态一致。

Mode:

sync

模式：

sync

The writing mode, and safe to run repeatedly by construction.

Run

list

's join first, because

sync

acts on exactly those verdicts.

写入模式，且设计为可安全重复执行。

先执行

list

的关联操作，因为

sync

会根据这些判定结果进行操作。

Straight through, no confirmation

直接执行，无需确认

Every operation below is non-destructive and proven so, so none of them asks.

Register each

unregistered

worktree:

paseo workspace create --isolation local --path "$WT" \
  --project "$PROJECT_ID" --title "$TITLE" --json

--isolation local

is correct even though the target is a worktree: it tells Paseo to adopt the checkout at

$WT

rather than create one. Paseo introspects git and records

kind: "worktree"

, the branch, and

mainRepoRoot

on its own.

--project
is mandatory. Without it Paseo creates a duplicate project rooted at the worktree path, the

stray project

above, which no CLI can delete. Resolve

$PROJECT_ID

from

projects.json

by matching

rootPath

to the main checkout with

archivedAt

null. If the id cannot be resolved, skip the registration and report it. A missing row is recoverable; a stray project is not.

Archive each

orphaned

row:

paseo workspace archive "$WORKSPACE_ID" --json

Collapse each

duplicate

set to one row: keep the row a live agent is attached to, otherwise the oldest by

createdAt

, and archive the rest.

Retitle rows whose title Paseo generated rather than a human:

paseo workspace rename "$WORKSPACE_ID" "$TITLE"

The title is

#<n> · <issue title>

, with

<n>

parsed from an

issue-<n>-<slug>

branch and the title read with

gh issue view "$N" --json title

. It degrades to the branch name when

gh

is unusable or the branch names no issue.

Only ever retitle a row whose
title
is null or exactly the branch name. Anything else was set by a human and is left alone, reported as a disagreement rather than overwritten.

Skip anything

busy

, naming the agent's short id in the report. Never archive a workspace with a live agent in it.

以下所有操作均为非破坏性且已验证，因此无需询问用户。

注册每个

unregistered

工作区：

paseo workspace create --isolation local --path "$WT" \
  --project "$PROJECT_ID" --title "$TITLE" --json

--isolation local

是正确的参数，即使目标是工作区：它告诉 Paseo 接管

$WT

路径下的检出项，而非创建新的检出项。Paseo 会自行检查 Git 并记录

kind: "worktree"

、分支以及

mainRepoRoot

。

--project

是必填项。**如果未指定，Paseo 会创建一个以工作区路径为根的重复项目，即上面提到的“游离项目”，且没有 CLI 可以删除它。通过匹配

rootPath

与未归档的主检出项，从

projects.json

中解析

$PROJECT_ID

。**如果无法解析 ID，请跳过注册并报告该问题。**缺少条目可恢复，但游离项目无法处理。

归档每个

orphaned

条目：

paseo workspace archive "$WORKSPACE_ID" --json

合并每个

duplicate

条目集合为一个条目：保留关联了活跃 agent 的条目，否则保留创建时间最早的条目，并归档其余条目。

重命名那些由 Paseo 自动生成而非人工设置标题的条目：

paseo workspace rename "$WORKSPACE_ID" "$TITLE"

标题格式为

#<n> · <issue title>

，其中

<n>

从

issue-<n>-<slug>

格式的分支中解析，标题通过

gh issue view "$N" --json title

获取。当

gh

不可用或分支未关联议题时，标题会降级为分支名称。

**仅对

title

为 null 或恰好等于分支名称的条目进行重命名。**其他任何标题都是人工设置的，会保留原样，并报告为不一致情况而非覆盖。

跳过所有

busy

条目，并在报告中注明 agent 的短 ID。绝不要归档包含活跃 agent 的工作区。

Gated on one confirmation each

需单独确认的操作

Both of these widen the scope past what the user asked for, so both stop and ask.

Unknown repos. Walk

$WORKTREE_ROOT/*

, resolve each candidate to its main checkout with

git -C "$CANDIDATE" rev-parse --git-common-dir

, and collect the repos Paseo has never seen. List them, then on one OK register the main checkout first:

paseo workspace create --isolation local --path "$REPO" --json

That call is what brings the project into being. Re-read

projects.json

afterward for the new

prj_…

id, then register the repo's worktrees with it.

Paseo's own worktrees need no special case. They already carry a row, and their

--git-common-dir

resolves to a repo Paseo knows, so they never reach the unknown-repo bucket, and no hash-directory pattern has to be guessed at.

Tombstones. An archived row suppresses re-registration: someone archived that workspace deliberately, and re-adding it on the next run would undo the decluttering they just did. Name the tombstoned worktrees, restore them on one OK, and leave them alone otherwise.

There is no
paseo workspace unarchive
in 0.4.0. "Restoring" a tombstone means creating a fresh row for the same path, so the archived row stays in

workspaces.json

and the restored workspace is a new

wks_…

id. Say that when you do it; do not report a resurrection.

这两类操作的范围超出了用户的请求，因此需要停止并询问用户。

未知仓库：遍历

$WORKTREE_ROOT/*

，通过

git -C "$CANDIDATE" rev-parse --git-common-dir

将每个候选路径解析为主检出项，并收集 Paseo 从未识别过的仓库。列出这些仓库，在用户确认后先注册主检出项：

paseo workspace create --isolation local --path "$REPO" --json

该调用会将项目纳入 Paseo。之后重新读取

projects.json

获取新的

prj_…

ID，再使用该 ID 注册仓库的工作区。

Paseo 自身的工作区无需特殊处理。它们已经存在条目，且其

--git-common-dir

会解析为 Paseo 已识别的仓库，因此永远不会进入未知仓库的列表，无需猜测哈希目录模式。

已归档条目：已归档的条目会阻止重新注册——用户特意归档了该工作区，在下一次运行时重新添加会撤销他们刚刚完成的清理操作。列出已归档的工作区，在用户确认后恢复它们，否则保持原样。

Paseo 0.4.0 中没有
paseo workspace unarchive
命令。“恢复”已归档条目意味着为同一路径创建一个新条目，因此已归档条目仍会保留在

workspaces.json

中，恢复后的工作区会拥有新的

wks_…

ID。执行此操作时请明确告知用户；不要报告为“恢复”操作。

Hand off

后续操作

What changed. Report registrations, archives, collapses, and retitles, each with a count. Name every skip with its reason. Put

busy

skips first, because those are live work.

Where it landed. Paseo's registry only. Say plainly that no directory, branch, or git registration changed, and that the sidebar reflects the new rows within a few seconds.

Next. Crown one:

anything
busy
→ name the path and the agent. Tell the user to run
```
sync
```
again after that agent finishes.
any
stray project
→ name it. Say that the fix is manual: edit
```
~/.paseo/projects/projects.json
```
, then run
```
paseo restart
```
. Do not perform it, because a daemon restart kills every running agent, including the one reading this.
any
reapable
→ route to gitkit teardown, otherwise
```
git -C "$REPO" worktree remove "$WT"
```
followed by
```
sync
```
again to archive the row.
tracker drift → route to issuekit
```
close <n>
```
, otherwise
```
gh issue close <n>
```
.
nothing left → say the registry matches the disk and stop. This is not a loop worth repeating.

变更内容：报告注册、归档、合并和重命名的操作数量。列出所有跳过的条目及其原因。优先显示

busy

跳过的条目，因为这些是正在进行的工作。

当前状态：仅变更了 Paseo 的注册表。明确告知用户没有修改任何目录、分支或 Git 注册信息，且侧边栏会在几秒内反映新的条目。

下一步：根据情况推荐：

存在
busy
条目 → 注明路径和 agent。告知用户在该 agent 完成后重新运行
```
sync
```
。
存在
stray project
→ 注明该项目。说明修复方式为手动操作：编辑
```
~/.paseo/projects/projects.json
```
，然后执行
```
paseo restart
```
。不要自行执行，因为重启守护进程会终止所有运行中的 agent，包括正在读取此内容的 agent。
存在
reapable
条目 → 引导至 gitkit 清理操作，否则执行
```
git -C "$REPO" worktree remove "$WT"
```
，然后重新运行
```
sync
```
来归档条目。
跟踪系统脱节 → 引导至 issuekit 的
```
close <n>
```
命令，否则执行
```
gh issue close <n>
```
。
无剩余操作 → 告知用户注册表已与磁盘状态一致，停止操作。无需重复执行。

Mode:

align

模式：

align

One-time configuration, per machine. It does not touch a single workspace.

Check the worktree root. Compare

worktrees.root

~/.paseo/config.json

against

$WORKTREE_ROOT

, which is gitkit's convention, defaulting to

~/worktrees

unless the environment says otherwise. Two roots in play means every sweep classifies by path forever.

Aligning it only affects worktrees Paseo creates itself. Existing worktrees are untouched, and git stores absolute paths, so nothing moves. Say that out loud, because "aligned" reads like "migrated" and it is not.

Surface
daemon.autoArchiveAfterMerge
. Setting it

true

lets Paseo archive a workspace by itself when its change request merges, which would cover part of

sync

's reaping natively. Recommend it as an experiment to observe, and flag both limits honestly: it is undocumented, and it only reaches workspaces where Paseo detected a pull request.

sync

still owns the general case either way.

一次性配置，针对单台机器。不会修改任何工作区。

**检查工作区根目录。**将

~/.paseo/config.json

中的

worktrees.root

与

$WORKTREE_ROOT

进行比较——

$WORKTREE_ROOT

是 gitkit 的约定，默认值为

~/worktrees

，除非环境变量另有指定。存在两个根目录意味着每次扫描都会永久按路径分类。

对齐操作仅会影响 Paseo 自行创建的工作区。现有工作区不会被修改，且 Git 存储的是绝对路径，因此不会有任何内容移动。请明确告知用户这一点，因为“对齐”容易被误解为“迁移”，但实际并非如此。

**显示

daemon.autoArchiveAfterMerge

设置。**将其设置为

true

可让 Paseo 在变更请求合并后自动归档工作区，这可原生覆盖

sync

的部分清理功能。推荐用户将其作为实验进行观察，并诚实地说明其局限性：该设置未被文档化，且仅适用于 Paseo 检测到拉取请求的工作区。无论如何，

sync

仍负责通用场景的处理。

Hand off

后续操作

What changed. Report which config keys you compared, and which the user chose to change.

Where it landed. Report

~/.paseo/config.json

. Repeat that existing worktrees stayed where they were.

Next. Run

list

to see the whole set in one table. Then stop. This is a one-time setting per machine, not a routine.

变更内容：报告已比较的配置键，以及用户选择修改的键。

当前状态：报告修改了

~/.paseo/config.json

。再次强调现有工作区未发生移动。

下一步：执行

list

以在一个表格中查看所有工作区。然后停止操作。这是针对单台机器的一次性设置，而非常规操作。

Notes

注意事项

paseokit is machine-local and always optional. No Paseo on the box means no-op, and nothing else in the workflow may depend on it. gitkit, issuekit, and the rest never call it, because they would break on every machine without the tool. It is a pump you run, not a link in a chain.
orcakit
is the sibling, not the predecessor. It reconciles the same worktrees into Orca, whose model is the exact inverse: Orca discovers worktrees on its own and knows nothing about them, so orcakit enriches and cleans up, while paseokit registers and reaps. Both are machine-local and optional, and neither ever calls the other.
Worktree facts belong to gitkit. The path convention
```
$WORKTREE_ROOT/<repo>/<branch>
```
and the
```
issue-<n>-<slug>
```
branch grammar appear here only as declared portability fallbacks for machines without gitkit. Branch naming, base-ref resolution, and the teardown rules live there, and any other copy of a gitkit fact in this file is a bug.
Tracker facts belong to issuekit. paseokit reads issue and pull request state to build a title and a verdict; it writes none of it.
Read-only modes run straight through; scope-widening ones ask.
```
list
```
never asks.
```
sync
```
runs its non-destructive work without a prompt precisely because archiving cannot lose anything, and stops only for the two operations that register something the user did not name.
Never write into
~/.paseo/projects/*.json
. paseokit reads those files because 0.4.0 exposes no CLI equivalent, and writes exclusively through
```
paseo
```
. A hand-edited state file needs a daemon restart to take effect, and a restart kills every running agent.
No shell available? Then you cannot reach the
```
paseo
```
CLI,
```
git
```
, or
```
gh
```
. Reason from what the user gives you and print the exact commands as a codeblock for them to run, and never report a workspace registered or archived that you could not perform.

**paseokit 是机器本地工具，且始终为可选。**机器上没有 Paseo 时该工具会无操作，且工作流中的其他环节不会依赖它。gitkit、issuekit 及其他工具绝不会调用它，否则会在没有该工具的机器上运行失败。它是一个按需运行的工具，而非工作流中的必要环节。
**
```
orcakit
```
是同级工具，而非前置工具。**它会将相同的工作区同步到 Orca，其模型与 Paseo 完全相反：Orca 会自动发现工作区但对其一无所知，因此 orcakit 负责增强和清理，而 paseokit 负责注册和清理。两者均为机器本地工具且可选，彼此绝不会调用对方。
**工作区相关规则属于 gitkit。**路径约定
```
$WORKTREE_ROOT/<repo>/<branch>
```
和
```
issue-<n>-<slug>
```
分支格式仅作为无 gitkit 机器的可移植回写出现在此处。分支命名、基准引用解析和清理规则都存储在 gitkit 中，本文件中任何其他 gitkit 规则的副本均为错误。
跟踪系统相关规则属于 issuekit。 paseokit 仅读取议题和拉取请求的状态来生成标题和判定结果；绝不会写入任何内容。
只读模式直接执行；扩大范围的操作需询问。
```
list
```
模式绝不会询问。
```
sync
```
模式会直接执行非破坏性操作，正是因为归档不会丢失任何内容，仅会在执行用户未指定的注册操作时停止并询问。
切勿写入
~/.paseo/projects/*.json
。 paseokit 读取这些文件是因为 0.4.0 版本没有提供对应的 CLI，且仅通过
```
paseo
```
进行写入。手动编辑状态文件需要重启守护进程才能生效，而重启会终止所有运行中的 agent。
无 shell 可用？此时无法访问
paseo
CLI、
git
或
gh
。根据用户提供的信息进行推理，并将确切命令作为代码块打印供用户执行，绝不要报告未实际执行的工作区注册或归档操作。

paseokit

Original

Translation

paseokit

paseokit

The line paseokit does not cross

paseokit 不会跨越的边界

When this fires

触发场景

Preflight (every mode)

预检（所有模式通用）

What Paseo knows about a workspace

Paseo 对工作区的认知

Two things the registry gets wrong

注册表存在的两个问题

Mode:
`list`

模式：
`list`

Hand off

后续操作

Mode:
`sync`

模式：
`sync`

Straight through, no confirmation

直接执行，无需确认

Gated on one confirmation each

需单独确认的操作

Hand off

后续操作

Mode:
`align`

模式：
`align`

Hand off

后续操作

Notes

注意事项

paseokit

Original

Translation

paseokit

paseokit

The line paseokit does not cross

paseokit 不会跨越的边界

When this fires

触发场景

Preflight (every mode)

预检（所有模式通用）

What Paseo knows about a workspace

Paseo 对工作区的认知

Two things the registry gets wrong

注册表存在的两个问题

Mode: list

模式：list

Hand off

后续操作

Mode: sync

模式：sync

Straight through, no confirmation

直接执行，无需确认

Gated on one confirmation each

需单独确认的操作

Hand off

后续操作

Mode: align

模式：align

Hand off

后续操作

Notes

注意事项

Mode:
`list`

模式：
`list`

Mode:
`sync`

模式：
`sync`

Mode:
`align`

模式：
`align`