Back to Details

herdr-runtime

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Herdr Runtime

Herdr Runtime

Layer: Practice
Herdrはproject-initのlogical Worker / Supervisor modelを実装するoptional runtime adapterである。
Herdr固有のworkspace / pane / agent stateをorganizational truthへ昇格させない。canonical semanticsは 
organization/execution-roles.md
、ADR-0019、
parallel-orchestration
、
agent-recovery
に従う。
层级：Practice
Herdr 是实现 project-init logical Worker / Supervisor model 的可选 runtime adapter。
不会将 Herdr 特有的 workspace / pane / agent state 提升为 organizational truth。canonical semantics 遵循 
organization/execution-roles.md
、ADR-0019、
parallel-orchestration
、
agent-recovery
。

When to use

何时使用

Herdrは次の場合に有効:
  • 複数の独立Claude Code / Codex / OpenCode等を同時に走らせる
  • long-running/background Workerを人間が一覧監視したい
  • top-level agent同士をCLIからprompt / wait / readしたい
  • terminal sessionをdetachして継続したい
  • provider/runtimeの異なるWorkerを一つのoperational surfaceで扱いたい
次の場合はHerdr Workerへ昇格させないdefaultを優先する:
  • 1つのClaude/OpenCode内部で完結する短いnative research subagent
  • independent lifecycleを必要としないreview/explore
  • orchestration overheadがtask価値を上回るwork
Herdr 适用于以下情况：
  • 同时运行多个相互独立的 Claude Code / Codex / OpenCode 等实例
  • 希望人工通过列表监控 long-running/background Worker
  • 希望从 CLI 对 top-level agent 之间执行 prompt / wait / read
  • 希望 detach terminal session 并让其继续运行
  • 希望在同一个 operational surface 中管理 provider/runtime 不同的 Worker
以下情况默认优先不将其提升为 Herdr Worker：
  • 可在单个 Claude/OpenCode 内部完成的简短 native research subagent
  • 不需要 independent lifecycle 的 review/explore
  • orchestration overhead 高于 task 价值的 work

Preconditions

前置条件

herdr
が利用可能か確認する。
Herdr-managed pane内では 
HERDR_ENV=1
が設定される。必要に応じて 
HERDR_PANE_ID
/ 
HERDR_WORKSPACE_ID
をtransient runtime identityとして利用できるが、durable task identityの代替にしない。
agent-specific integrationを使用する場合はcurrent Herdr CLIで確認してから導入する。現行CLIでは例として:
bash
herdr integration install claude
herdr integration install codex
herdr integration install opencode
herdr integration status
integrationはstate/session detectionを改善するPracticeであり、project evidenceのSoTではない。
确认 
herdr
可用。
在 Herdr-managed pane 内会设置 
HERDR_ENV=1
。可以按需将 
HERDR_PANE_ID
/ 
HERDR_WORKSPACE_ID
用作 transient runtime identity，但不将其作为 durable task identity 的替代品。
使用 agent-specific integration 时，应先通过 current Herdr CLI 确认后再引入。当前 CLI 的示例如下：
bash
herdr integration install claude
herdr integration install codex
herdr integration install opencode
herdr integration status
integration 是改善 state/session detection 的 Practice，而不是 project evidence 的 SoT。

Responsibility split

职责划分

LayerResponsibility
project-initwork unit / attempt class / authority / evidence / admission / recovery semantics
Worktrunk or selected Git workspace Practicebranch/worktree materialization
sandbox/runtimefilesystem/process/service/network/credential mutable ownership
Herdrterminal, pane, top-level agent lifecycle, transient state/observability
native coding-agent subagentsone top-level Worker内部のtemporary delegation
Herdrの 
worktree create
等をWorktrunkの自動代替として使わない。workspace mechanismを変更する場合はADR-0017のrefinement contractで比較する。
层级职责
project-initwork unit / attempt class / authority / evidence / admission / recovery 语义
Worktrunk 或所选 Git workspace Practicebranch/worktree 实体化
sandbox/runtimefilesystem/process/service/network/credential 的可变所有权
Herdrterminal、pane、top-level agent lifecycle、transient state/可观测性
native coding-agent subagents一个 top-level Worker 内部的 temporary delegation
不要将 Herdr 的 
worktree create
等命令用作 Worktrunk 的自动替代方案。若要变更 workspace mechanism，应依据 ADR-0017 的 refinement contract 进行比较。

Mapping

映射

project-init logical capabilityからHerdrへmappingする場合のcurrent shape:
Logical capabilityHerdr Practice
create execution surface
workspace create
/ 
tab create
/ 
pane split
spawn Worker agent
agent start
discover/observe
agent list
/ 
agent get
send work
agent prompt
wait
agent wait
inspect result/UI
agent read
human takeover
agent attach
interactive interrupt
agent send-keys ... ctrl+c
terminal teardown
pane close
/ workspace lifecycle
このmappingはcommand compatibility layerであり、organizational contractではない。
特にcancelは 
ctrl+c
を送っただけで完了とみなさない。process/agent stateとdurable side effectをreconcileし、durable Workerならfencing ownershipを更新してからreplacement attemptをadmitする。
将 project-init logical capability 映射到 Herdr 时，当前形态如下：
Logical capabilityHerdr Practice
创建 execution surface
workspace create
/ 
tab create
/ 
pane split
启动 Worker agent
agent start
发现/观察
agent list
/ 
agent get
发送任务
agent prompt
等待
agent wait
检查结果/UI
agent read
人工接管
agent attach
交互式中断
agent send-keys ... ctrl+c
终端拆除
pane close
/ workspace lifecycle
此映射是 command compatibility layer，而不是 organizational contract。
尤其是 cancel 操作，不能仅因发送了 
ctrl+c
就视为完成。应 reconcile process/agent state 与 durable side effect；对于 durable Worker，必须先更新 fencing ownership，再 admit replacement attempt。

Agent-driven Supervisor loop

Agent 驱动的 Supervisor 循环

Herdr-managedなCoordinator / Supervisor agentは、
HERDR_ENV=1
を確認したうえでHerdr CLI/APIからsibling top-level Workerを起動・委譲・回収してよい。fan-out判断は 
parallel-orchestration
のadaptive policyに従い、Herdr paneを増やすこと自体を目的にしない。
current command surfaceでは概ね次を使用する。
bash
herdr agent list
herdr agent start <worker-name> --kind <agent-kind> --pane <pane-id>
herdr agent prompt <worker-name> "<bounded-task>" --wait --timeout <ms>
herdr agent read <worker-name> --source recent-unwrapped --lines <n>
workspace / tab / pane creationを行う場合はcommandが返したJSON IDを取得し、IDやpane placementを推測しない。
Supervisor loop:
  1. execution profile / dependency / attempt class / fan-out modeを決める。
  2. mutable WorkerならHerdrより先にworkspace/runtime ownershipをmaterializeする。
  3. execution surfaceとagentを作る。
  4. bounded task contractをpromptする。
  5. agent wait
    / 
    agent read
    / lifecycle telemetryでobserveする。
  6. blocked
    、timeout、
    agent_prompt_stalled
    等をreconcileしてからretry/reassignする。
  7. immutable result / evidenceを回収し、base / fencing / validation / authorityを確認する。
  8. remaining workとbottleneckを再評価し、spawn / continue / stopを選ぶ。
official Herdr Agent Skillはcommand adapterとして利用できるが、project-initのattempt / ownership / evidence / admission semanticsを置換しない。導入する場合はproject-local Skill policyに従うか、
herdr --skill
等のinstalled releaseに対応したsourceを利用し、global installationをproject correctnessの前提にしない。
remote machineを使う場合はtargetを明示する。machine/server failure後に別machineやlocalへsilent fallbackして同じmutable attemptを二重継続しない。
由 Herdr 管理的 Coordinator / Supervisor agent 在确认 
HERDR_ENV=1
后，可以通过 Herdr CLI/API 启动、委派和回收同级 top-level Worker。fan-out 判断应遵循 
parallel-orchestration
的 adaptive policy，不以增加 Herdr pane 本身为目标。
当前 command surface 大致使用以下命令。
bash
herdr agent list
herdr agent start <worker-name> --kind <agent-kind> --pane <pane-id>
herdr agent prompt <worker-name> "<bounded-task>" --wait --timeout <ms>
herdr agent read <worker-name> --source recent-unwrapped --lines <n>
创建 workspace / tab / pane 时，应获取命令返回的 JSON ID，不得猜测 ID 或 pane placement。
Supervisor loop：
  1. 确定 execution profile / dependency / attempt class / fan-out mode。
  2. 如果 Worker 是 mutable，应先于 Herdr materialize workspace/runtime ownership。
  3. 创建 execution surface 和 agent。
  4. 使用 bounded task contract 发送 prompt。
  5. 通过 
    agent wait
    / 
    agent read
    / lifecycle telemetry 进行 observe。
  6. 先 reconcile 
    blocked
    、timeout、
    agent_prompt_stalled
    等状态，再执行 retry/reassign。
  7. 回收 immutable result / evidence，并确认 base / fencing / validation / authority。
  8. 重新评估 remaining work 和 bottleneck，选择 spawn / continue / stop。
官方 Herdr Agent Skill 可以作为 command adapter 使用，但不能替换 project-init 的 attempt / ownership / evidence / admission semantics。引入时，应遵循 project-local Skill policy，或使用与 
herdr --skill
等 installed release 相匹配的 source；不得将 global installation 作为 project correctness 的前提。
使用 remote machine 时，应明确指定 target。machine/server 故障后，不得 silent fallback 到其他 machine 或 local 并让同一个 mutable attempt 双重继续执行。

Spawn flow

Spawn 流程

  1. objective / acceptance criteria / authorityを読む。
  2. ADR-0019に従い observational / mutable / durable attemptを分類する。
  3. mutable attemptなら先にrequired workspace/runtime isolationをmaterializeする。
  4. Herdr workspace/tab/paneを作る。
  5. creation commandが返したJSONのIDを使い、IDを予測しない。
  6. supported top-level agentを 
    agent start
    するか、既存agentをdetect/renameする。
  7. execution attempt metadataへHerdr workspace/pane/agent nameをtransient referenceとして関連付ける。
  8. promptを送る。
  9. agent wait
    / 
    agent read
    でobserveする。
  10. project-init result/evidence contractを満たすartifactを回収する。
  11. applicable fencing / validation / admission check後にのみorganizational resultへ採用する。
workspace creation example:
bash
created=$(herdr workspace create --cwd <workspace-path> --label <label> --no-focus)
pane_id=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id')
agent start example:
bash
herdr agent start <worker-name> --kind claude --pane "$pane_id"
agent kind / optionsはcurrent installed Herdr / provider CLIを確認して決める。model flag等をproject policyへ固定しない。
  1. 阅读 objective / acceptance criteria / authority。
  2. 遵循 ADR-0019，将 attempt 分类为 observational / mutable / durable。
  3. 如果 attempt 是 mutable，应先 materialize 所需的 workspace/runtime isolation。
  4. 创建 Herdr workspace/tab/pane。
  5. 使用 creation command 返回的 JSON ID，不得预测 ID。
  6. 使用 
    agent start
    启动 supported top-level agent，或 detect/rename 现有 agent。
  7. 将 Herdr workspace/pane/agent name 作为 transient reference 关联到 execution attempt metadata。
  8. 发送 prompt。
  9. 通过 
    agent wait
    / 
    agent read
    进行 observe。
  10. 回收满足 project-init result/evidence contract 的 artifact。
  11. 仅在通过适用的 fencing / validation / admission check 后，才将其采纳为 organizational result。
workspace creation 示例：
bash
created=$(herdr workspace create --cwd <workspace-path> --label <label> --no-focus)
pane_id=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id')
agent start 示例：
bash
herdr agent start <worker-name> --kind claude --pane "$pane_id"
agent kind / options 应通过检查当前已安装的 Herdr / provider CLI 确定。不要将 model flag 等固定到 project policy 中。

Prompt / wait / read

Prompt / wait / read

例:
bash
herdr agent prompt <worker-name> "<task>" --wait --timeout 120000
herdr agent read <worker-name> --source recent-unwrapped --lines 120
重要:
  • blocked
    はhuman/approval/inputが必要なsignalとして扱う。
  • working
    は実行中signal。
  • done
    / 
    idle
    はinput可能状態であり、acceptance criteria達成を意味しない。
  • unknown
    を成功扱いしない。
  • timeout / 
    agent_prompt_stalled
    は「prompt未送信」の証拠ではない。retry前にread/getしてreconcileする。
  • waitにはbounded timeoutを指定し、永続hangをSupervisor logicへ持ち込まない。
示例：
bash
herdr agent prompt <worker-name> "<task>" --wait --timeout 120000
herdr agent read <worker-name> --source recent-unwrapped --lines 120
重要：
  • 将 
    blocked
    视为需要 human/approval/input 的 signal。
  • working
    表示正在执行的 signal。
  • done
    / 
    idle
    表示可以接受输入的状态，并不意味着已经达到 acceptance criteria。
  • 不得将 
    unknown
    当作成功。
  • timeout / 
    agent_prompt_stalled
    并不能证明 prompt 未发送。retry 前应先执行 read/get 并完成 reconcile。
  • 为 wait 指定 bounded timeout，避免将永久 hang 带入 Supervisor logic。

Native subagents

Native subagents

top-level Claude Code等の内部subagentは、Herdr上で別paneとして可視化することを要求しない。
text
Herdr Worker: Claude Code
  ├─ native Explore subagent
  ├─ native Reviewer subagent
  └─ native temporary helper
でよい。
次の場合だけ別Herdr Workerを検討する:
  • independent mutable workspaceを持つ
  • parent process loss後も継続させたい
  • provider/model/toolを分離したい
  • independent cost/budget/lifecycleを持つ
  • humanがtop-level lifecycleを直接監視/attachする価値がある
top-level Claude Code 等内部的 subagent，不要求在 Herdr 上作为单独的 pane 可视化。
text
Herdr Worker: Claude Code
  ├─ native Explore subagent
  ├─ native Reviewer subagent
  └─ native temporary helper
采用上述结构即可。
仅在以下情况下，才考虑使用独立的 Herdr Worker：
  • 拥有独立的 mutable workspace
  • 希望在 parent process 丢失后继续运行
  • 需要分离 provider/model/tool
  • 拥有独立的 cost/budget/lifecycle
  • 人工直接监控/attach top-level lifecycle 具有实际价值

Worktrunk integration

Worktrunk 集成

WSL/LinuxでWorktrunkを使用するprofileでは:
  1. Worktrunk / selected workspace Practiceでexpected branch/worktreeをmaterializeする。
  2. sandbox/runtime policyで必要なmutable resourcesを分離する。
  3. そのworkspace pathをHerdr workspaceのcwdへ渡す。
  4. Herdrはagent/session lifecycleだけを所有する。
Herdr workspace pathやpane IDをGit branch / Issue identityとして推測しない。
对于在 WSL/Linux 上使用 Worktrunk 的 profile：
  1. 通过 Worktrunk / 所选 workspace Practice materialize 预期的 branch/worktree。
  2. 通过 sandbox/runtime policy 隔离所需的 mutable resources。
  3. 将该 workspace path 作为 Herdr workspace 的 cwd 传入。
  4. Herdr 仅负责 agent/session lifecycle。
不要将 Herdr workspace path 或 pane ID 推断为 Git branch / Issue identity。

Recovery

恢复

Herdr detach/reattachはsoft continuityとして利用できる。
ただしdurable WorkerはHerdr process persistenceだけに依存しない。
server/host/provider loss後は:
  1. durable Issue/PR/Git/checkpointを読む。
  2. current fencing ownershipを取得する。
  3. Herdrに残るagent/sessionがあればreconcileする。
  4. stale attempt resultをadmitしない。
  5. 必要なら新Herdr workspace/agentを作り直す。
native session restoreが利用できても、それだけをcanonical recovery mechanismにしない。
Herdr detach/reattach 可以用作 soft continuity。
但是，durable Worker 不能仅依赖 Herdr process persistence。
server/host/provider 丢失后：
  1. 读取 durable Issue/PR/Git/checkpoint。
  2. 获取 current fencing ownership。
  3. 如果 Herdr 中仍存在 agent/session，则执行 reconcile。
  4. 不得 admit stale attempt result。
  5. 必要时重新创建 Herdr workspace/agent。
即使可以使用 native session restore，也不应仅将其作为 canonical recovery mechanism。

Cleanup

清理

pane/workspaceを閉じる前に:
  • required immutable resultが回収済み
  • validation/evidence identityが記録済み
  • consequential side effectがreconcile済み
  • durable checkpointが必要なら作成済み
  • uncommitted unique workを失わない
ことを確認する。
关闭 pane/workspace 前，确认以下事项：
  • 所需的 immutable result 已回收
  • validation/evidence identity 已记录
  • consequential side effect 已完成 reconcile
  • 如有需要，已创建 durable checkpoint
  • 不会丢失 uncommitted unique work

Official references

官方参考

Current reference documentation:
Herdr command shapeが変わった場合は本Skillを更新する。Constitution/Operating ModelをHerdr commandへ合わせて変更しない。
当前参考文档：
如果 Herdr command shape 发生变化，应更新本 Skill。不要为了迎合 Herdr command 而修改 Constitution/Operating Model。

Remove / re-evaluate

移除或重新评估

  • native runtimeが同等以上のtop-level Worker lifecycleを提供する
  • Herdr CLI/APIが大きく変更される
  • agent state detectionがselected providerで信頼できない
  • remote execution中心になりlocal terminal runtimeが不要になる
  • adapter maintenance costがbenefitを上回る
出现以下情况时，应移除或重新评估 Herdr：
  • native runtime 提供了同等或更优的 top-level Worker lifecycle
  • Herdr CLI/API 发生重大变更
  • agent state detection 在 selected provider 上不可靠
  • 工作重心转向 remote execution，local terminal runtime 不再需要
  • adapter maintenance cost 高于其带来的 benefit