worktree

Documentation

Overview

Package worktree owns the Workspace identity of the Task/Session/Workspace triad (multi-task-concurrency design §4, L1).

包 worktree 承载 Task/Session/Workspace 三元组中的 Workspace 身份 （multi-task-concurrency 设计 §4，L1）。一个 Workspace = 一个工作树——主检出或某个 linked git worktree——其 ID（wtid）是 EvalSymlinks 解析后绝对路径的 hash12。 绑定存储与归属台账都按 wtid 键控：一切路径形状的东西按构造即机器本地。

Index

• func BindTask(root, taskRef, branch, sessionID string) error
• func Clear(root, taskRef string) error
• func ClearAllForTask(root, taskRef string) error
• func ClearByID(root, id, taskRef string) error
• func ID(root string) string
• func Touch(root string)
• type Binding
  • func Load(root string) *Binding

Functions

func BindTask

func BindTask(root, taskRef, branch, sessionID string) error

BindTask upserts the cwd→taskRef binding (multi-task-concurrency §4).

BindTask upsert cwd→taskRef 绑定（multi-task-concurrency §4）。对已绑定 workspace 重新绑定即改指（在已绑定目录里 task start = 显式切换，最后显式动作胜），但保留 原始 CreatedBy/CreatedAt 以便追溯。

func Clear

func Clear(root, taskRef string) error

Clear removes the workspace binding when it still points at taskRef (a stale clear for another task must not unbind a newer switch — compare before delete).

Clear 仅当绑定仍指向 taskRef 时移除（为别的任务做的过期 clear 不得解掉更新的切换 ——先比对再删）。

func ClearAllForTask

func ClearAllForTask(root, taskRef string) error

ClearAllForTask removes EVERY binding file whose TaskRef matches — the task-scoped sweep（dogfood #4 深挖，2026-08-27）：abort 一个 --worktree 任务时，cwd 键控的 Clear 只能清调用方所在目录的绑定，任务的 worktree 绑定无人清；任务被 abort/ 删除后，任何指向它的绑定都是死锚。幂等，静默容忍读取失败。

func ClearByID

func ClearByID(root, id, taskRef string) error

ClearByID removes the binding file by wtid, resolved inside ANY live root of the same project（dogfood 发现 #4，2026-08-27）：finish 先删 worktree 目录再解绑时，原路径 已消失——DataDirFor(消失路径) 的身份推导漂移、Clear 静默 no-op，绑定残留。按 ID 直删 + TaskRef 比对，不依赖原路径存活；幂等（文件缺失即成功）。

func ID

func ID(root string) string

ID derives the workspace identity of root: hash12 (fnv-64a, %012x) of the EvalSymlinks-resolved absolute path.

ID 推导 root 的 workspace 身份：EvalSymlinks 解析后绝对路径的 hash12（fnv-64a， %012x）。与 forgedata.Key 的路径 hash 同族推导（fnv-64a → 12 hex），生态读起来一 致；刻意不用 project key——同一 repo 的所有 worktree 共享 project key 但必须有不同 wtid，这个区分正是三元组的意义。解析失败（路径消失）回落到清洗后的绝对路径： 身份必须是全函数。

func Touch

func Touch(root string)

Touch refreshes the heartbeat (display-only; resolution never gates on it).

Touch 刷新心跳（仅展示用；解析从不对它设门）。尽力而为静默——分发器每个 hook 顺带调用。

Types

type Binding

type Binding struct {
	ID         string    `json:"id"`         // wtid
	Path       string    `json:"path"`       // EvalSymlinks 后的绝对路径
	Branch     string    `json:"branch"`     // 绑定时分支（展示用；解析以 TaskRef 为准）
	TaskRef    string    `json:"task_ref"`   // 绑定的任务
	CreatedBy  string    `json:"created_by"` // 建绑会话
	Node       string    `json:"node"`       // 机器身份（跨机诊断；绑定本身本机性）
	CreatedAt  time.Time `json:"created_at"`
	LastSeenAt time.Time `json:"last_seen_at"` // heartbeat（hook dispatcher 顺带刷新；只影响展示不影响解析）
}

Binding is the durable cwd→task anchor of the Task/Session/Workspace triad (multi-task-concurrency design §4, L1). Unlike session pointers (which die with the session id) the binding is keyed by the workspace PATH: a new window in the same directory/worktree resolves the same task — "退出重进" works because the directory is stable, not because any session survived. Bindings are machine-local by construction (wtid is a path hash) and carry no freshness gate: existence IS the anchor.

Binding 是 Task/Session/Workspace 三元组中持久的 cwd→任务锚（multi-task-concurrency 设计 §4，L1）。与会话指针（随 session id 一起消亡）不同，绑定按 workspace 路径 键控：同一目录/worktree 里的新窗口解析到同一任务——「退出重进」之所以成立，是 因为目录稳定，不是因为任何会话还活着。绑定按构造即机器本地（wtid 是路径哈希）， 不带新鲜度门：存在即锚。

func Load

func Load(root string) *Binding

Load reads the workspace's binding; nil when absent/corrupt (degrade = no anchor, resolution falls through — the safe direction).

Load 读该 workspace 的绑定；缺失/损坏返回 nil（降级 = 无锚，解析穿落——安全方向）。