@kylecheng3146/agent-ops 0.2.8 → 0.3.1

package/dist/runtime/src/task/completion.js

@@ -38,7 +38,7 @@ export async function checkTaskCompletionEvidence(stored, options) {
             }
         }
     }
-    const attestation = await findReviewAttestation(root, sourceFingerprint);
+    const attestation = await findReviewAttestation(root, sourceFingerprint, stored.task.id);
     if (attestation === null || attestation.taskId !== stored.task.id) {
         return { status: "FAIL", code: "REVIEW_REQUIRED", remedy: `Run agent-ops review --task ${stored.task.id} --yes for the whole task and current source.` };
     }

package/dist/runtime/src/task/service.js

@@ -130,9 +130,17 @@ export class TaskService {
             state.tasks.push(record);
             if (input.sessionId !== undefined) {
                 const currentIndex = state.sessions.findIndex(({ sessionId }) => sessionId === input.sessionId);
+                // A subtask keeps the session on the top of its tree: the completion
+                // gate checks the attached task and everything under it, so attaching
+                // the subtask would let a Stop through with its parent unfinished.
+                let rootId = record.task.id;
+                for (let parentId = record.task.parentTaskId; parentId !== undefined;) {
+                    rootId = parentId;
+                    parentId = state.tasks.find(({ task }) => task.id === parentId)?.task.parentTaskId;
+                }
                 const attachment = {
                     sessionId: input.sessionId,
-                    taskId: record.task.id,
+                    taskId: rootId,
                     attachedAt: now
                 };
                 if (currentIndex === -1) {
@@ -304,7 +312,12 @@ export class TaskService {
      * task accepts evidence: a completed record must stay exactly as it was
      * verified.
      */
-    async recordEvidence(taskId, evidenceInput) {
+    async recordEvidence(taskId, evidenceInput, 
+    /**
+     * A PASS review's base: set records it, null clears it (the review covered
+     * uncommitted work), undefined leaves the record's value alone.
+     */
+    reviewBase) {
         const now = assertTimestamp(this.#now());
         return await this.#store.mutate((state) => {
             const current = findTask(state, taskId);
@@ -328,10 +341,13 @@ export class TaskService {
                     ...new Set([...(evidence[criterionId] ?? []), ...references])
                 ];
             }
+            const { reviewBase: previousBase, ...rest } = current;
+            const base = reviewBase === undefined ? previousBase : reviewBase ?? undefined;
             const updated = {
-                ...current,
+                ...rest,
                 evidence,
-                updatedAt: now
+                updatedAt: now,
+                ...(base === undefined ? {} : { reviewBase: base })
             };
             replaceTask(state, updated);
             return cloneRecord(updated);

package/dist/runtime/src/task/store.js

@@ -66,7 +66,7 @@ function parseTaskRecord(value) {
     ];
     // Every record written before an optional field existed must still parse, so
     // the accepted shapes are every combination of them.
-    const optionalKeys = ["completionBase", "failureFingerprint", "policyConfigHash"];
+    const optionalKeys = ["completionBase", "failureFingerprint", "policyConfigHash", "reviewBase"];
     const allowedKeys = new Set(Array.from({ length: 1 << optionalKeys.length }, (_unused, mask) => [
         ...baseKeys,
         ...optionalKeys.filter((_key, position) => (mask & (1 << position)) !== 0)
@@ -146,6 +146,10 @@ function parseTaskRecord(value) {
         (typeof completionBase !== "string" || !/^[a-f0-9]{40,64}$/u.test(completionBase))) {
         return invalidState("Task state contains an invalid completion base.");
     }
+    if (value.reviewBase !== undefined &&
+        (typeof value.reviewBase !== "string" || !/^[a-f0-9]{40,64}$/u.test(value.reviewBase))) {
+        return invalidState("Task state contains an invalid review base.");
+    }
     return {
         task: task.value,
         status,
@@ -156,7 +160,8 @@ function parseTaskRecord(value) {
         archivedAt: value.archivedAt,
         failureFingerprint,
         policyConfigHash,
-        completionBase
+        completionBase,
+        ...(value.reviewBase === undefined ? {} : { reviewBase: value.reviewBase })
     };
 }
 function parseSession(value) {

package/docs/en/guides/configuration.md

@@ -132,6 +132,69 @@ agent-ops doctor --check-auth # one real print call per target
 reports what to do but never fixes it: every target authenticates through
 interactive OAuth, so there is no `--fix`. Run `<target> login` yourself.
 
+### Parallel sessions in worktrees
+
+Verification, review and the completion gate all fingerprint the whole Git
+change surface, so two conversations editing one checkout void each other's
+evidence. Give each editing conversation its own worktree instead:
+
+```json
+{
+  "worktree": {
+    "mode": "auto",
+    "setup": [{ "command": "pnpm", "args": ["install", "--frozen-lockfile"] }]
+  }
+}
+```
+
+- `mode: "auto"` routes every editing conversation through
+  `agent-ops worktree add <name> --session <id>`, run from the main checkout.
+  On Claude Code a direct Edit or Write of the main checkout outside
+  `.worktrees/` is denied (run `agent-ops update` once so the PreToolUse hook
+  matches the file tools). Absent or `"off"` keeps today's single checkout.
+- `agent-ops task create` run from the main checkout with a known session
+  creates that session's worktree first (or reuses it) and records the task
+  there, so the work starts in the worktree. Its output names the path to
+  enter and the `--base` to verify against.
+- As a fallback on Claude Code, the first denied edit creates that worktree:
+  `.worktrees/session-<first eight characters of the session id>`, setup
+  included, bound to the session. The denial names the path to enter with
+  EnterWorktree; a later denial for the same session reuses it. If creation
+  fails, the denial says why and falls back to the manual `worktree add`.
+  Run `agent-ops update` once so the PreToolUse hook gets the 600-second
+  timeout setup needs.
+- `add` creates `.worktrees/<name>` on branch `agent-ops/<name>` from the main
+  checkout's HEAD and excludes `/.worktrees/` through `.git/info/exclude`,
+  never `.gitignore`. It copies the ignored files agent-ops installed and any
+  file matched by a root `.worktreeinclude` (gitignore syntax, for example
+  `.env` or `local.properties`); a file Git already checked out is never
+  overwritten. Trust is inherited only when the main checkout is trusted and
+  the worktree's effective config is identical.
+- `setup` commands run in the new worktree (default timeout ten minutes) for
+  what Git does not carry, such as installed dependencies. They are part of
+  the trusted config, so they need no separate approval; a failing step
+  removes the worktree again.
+- The session's completion gate follows it: Claude Code enters the worktree
+  with EnterWorktree, and a host that cannot move a session (agy) is judged by
+  the worktree's gate through a redirect the main checkout records.
+- In a worktree, verify and review each task but do not run `task complete`
+  (Claude Code refuses it inside an isolated worktree session). `agent-ops
+  worktree finish <name>` completes every non-archived task in the worktree,
+  subtasks before their parents, each against the base its PASS review
+  recorded (the worktree's base when none was recorded), before any rebase.
+  If one cannot complete, nothing merges and the error names the task.
+  Creating a subtask keeps the session attached to the top of its tree, and
+  each task keeps its own review record, so a parent and a subtask reviewed
+  on the same source do not overwrite each other.
+- `agent-ops worktree finish <name>` merges by fast-forward only, one finish
+  at a time. If the target moved, it rebases; a clean rebase whose own patch
+  is unchanged is re-verified before merging, and a conflict is reported with
+  the `refs/notes/agent-ops` intent of the work that landed first. The note
+  records every task of the worktree, subtasks indented under their parent.
+- `worktree list`, `resume <name> --session <id>` and `remove <name>` manage
+  what is left; `remove --force` discards work and asks the user first.
+  `doctor` reports worktrees idle for more than seven days.
+
 ### Project-local loop profile
 
 `--profile loop` is an opt-in project-scope profile. Select `codex`, `claude`,

package/docs/en/spec/delegation.md

@@ -29,3 +29,13 @@ Concurrent delegated writers MUST NOT share one working tree.
 - Evidence: `agent-ops verify` returns a status other than `UNKNOWN` for the run.
 - Positive: `Read-only scans run in parallel; the single edit runs in the coordinator worktree.`
 - Negative: `Two subagents edit the same files while verification runs.`
+
+## DELEGATE-ISOLATION-002
+
+Parallel editing conversations in one repository MUST each work in their own agent-ops worktree.
+
+- Trigger: `worktree.mode` is `auto`, or a second conversation will edit the repository while another is still open.
+- Action: Run `agent-ops worktree add <name> --session <id>` from the main checkout before the first edit, work only in the printed path, and merge with `agent-ops worktree finish <name>` after the task completes against the printed `--base`.
+- Evidence: `agent-ops worktree list` shows one worktree per editing session, and each finish reports a fast-forward merge.
+- Positive: `Two conversations edit .worktrees/login and .worktrees/cart; each verifies, reviews and finishes on its own.`
+- Negative: `Two conversations edit the main checkout at once, so each one's verification and review is voided by the other's writes.`

package/docs/zh-TW/guides/configuration.md

@@ -116,6 +116,61 @@ agent-ops doctor --check-auth # 每個目標一次真實 print 呼叫
 不會代為修復：所有目標都經由互動式 OAuth 認證，因此沒有 `--fix`。
 請自行執行 `<target> login`。
 
+### 在 worktree 中並行 session
+
+Verification、review 與 completion gate 都對整個 Git change surface 計算
+fingerprint，因此兩個對話修改同一個 checkout 會互相作廢對方的 evidence。
+請讓每個修改中的對話使用自己的 worktree：
+
+```json
+{
+  "worktree": {
+    "mode": "auto",
+    "setup": [{ "command": "pnpm", "args": ["install", "--frozen-lockfile"] }]
+  }
+}
+```
+
+- `mode: "auto"` 讓每個修改中的對話都先在主 checkout 執行
+  `agent-ops worktree add <name> --session <id>`。Claude Code 直接以 Edit 或
+  Write 修改主 checkout 中 `.worktrees/` 以外的檔案會被拒絕（需先執行一次
+  `agent-ops update`，讓 PreToolUse hook 比對檔案工具）。未設定或 `"off"` 則維持
+  目前的單一 checkout。
+- 在主 checkout、已知 session 的情況下執行 `agent-ops task create`，會先建立（或重用）
+  該 session 的 worktree，並把 task 記錄在那裡，讓工作一開始就在 worktree 內。輸出會列出
+  要進入的路徑與 verify 用的 `--base`。
+- 作為 Claude Code 上的後備，第一次被拒絕的編輯會自動建立該 worktree：
+  `.worktrees/session-<session id 前八個字元>`，包含 setup，並綁定該 session。
+  拒絕訊息會列出要以 EnterWorktree 進入的路徑；同一 session 之後被拒絕時會重用它。
+  建立失敗時，拒絕訊息會說明原因並退回手動 `worktree add`。需先執行一次
+  `agent-ops update`，讓 PreToolUse hook 取得 setup 所需的 600 秒逾時。
+- `add` 從主 checkout 的 HEAD 建立 `.worktrees/<name>` 與 branch
+  `agent-ops/<name>`，並透過 `.git/info/exclude`（而非 `.gitignore`）排除
+  `/.worktrees/`。它會複製 agent-ops 安裝的 ignored 檔案，以及根目錄
+  `.worktreeinclude`（gitignore 語法，例如 `.env` 或 `local.properties`）比對到
+  的檔案；Git 已 checkout 的檔案一律不覆寫。只有主 checkout 已 trusted 且
+  worktree 的 effective config 完全相同時才繼承 trust。
+- `setup` 指令在新 worktree 中執行（預設 timeout 十分鐘），處理 Git 不會帶過去
+  的東西，例如已安裝的相依套件。它屬於 trusted config 的一部分，不需另外核准；
+  任一步驟失敗會移除該 worktree。
+- Session 的 completion gate 會跟著它：Claude Code 以 EnterWorktree 進入
+  worktree；無法移動 session 的 host（agy）則透過主 checkout 記錄的 redirect，
+  由 worktree 的 gate 判定。
+- 在 worktree 裡對每個 task 執行 verify 與 review，但不要執行 `task complete`
+  （Claude Code 在隔離的 worktree session 中會拒絕它）。`agent-ops worktree finish
+  <name>` 會在任何 rebase 之前 complete worktree 內每個未封存的 task，先 subtask
+  後 parent，各自使用其 PASS review 記錄的 base（沒有記錄時使用 worktree 的 base）。
+  任一 task 無法完成時不會合併，錯誤訊息會指出是哪個 task。建立 subtask 時 session
+  維持附著在 task 樹最上層，且每個 task 各自保留 review 紀錄，所以在同一份原始碼上
+  review 的 parent 與 subtask 不會互相覆蓋。
+- `agent-ops worktree finish <name>` 只以 fast-forward 合併，一次只執行一個
+  finish。Target 若已前進會先 rebase；沒有衝突且自身 patch 不變的 rebase 會先
+  重新驗證再合併；衝突則連同先合併那份工作在 `refs/notes/agent-ops` 的意圖一起
+  回報。Note 會記錄 worktree 的每個 task，subtask 縮排在其 parent 之下。
+- `worktree list`、`resume <name> --session <id>` 與 `remove <name>` 管理剩下的
+  worktree；`remove --force` 會丟棄工作，執行前會先詢問使用者。`doctor` 會回報
+  閒置超過七天的 worktree。
+
 ### Project-local loop profile
 
 `--profile loop` 是明確 opt-in 的 project-scope profile。請選擇 `codex`、

package/docs/zh-TW/spec/delegation.md

@@ -1,6 +1,6 @@
 # 委派
 
-English source version: 2026-07-23. Revalidate: when the English specification changes.
+English source version: 2026-09-24. Revalidate: when the English specification changes.
 
 ## DELEGATE-SCOPE-001
 
@@ -31,3 +31,13 @@ English source version: 2026-07-23. Revalidate: when the English specification c
 - Evidence: `agent-ops verify` 該次執行回傳非 `UNKNOWN` 的狀態。
 - Positive: `唯讀掃描並行執行；唯一的修改在協調者工作區進行。`
 - Negative: `兩個 subagent 在驗證執行期間修改相同檔案。`
+
+## DELEGATE-ISOLATION-002
+
+同一個 repository 中並行修改檔案的對話 MUST 各自在自己的 agent-ops worktree 中工作。
+
+- Trigger: `worktree.mode` 為 `auto`，或另一個對話仍開著時，第二個對話也要修改這個 repository。
+- Action: 第一次修改前，在主 checkout 執行 `agent-ops worktree add <name> --session <id>`，只在印出的路徑中工作；task 以印出的 `--base` 完成後，用 `agent-ops worktree finish <name>` 合併。
+- Evidence: `agent-ops worktree list` 顯示每個修改中的 session 各有一個 worktree，且每次 finish 都回報 fast-forward 合併。
+- Positive: `兩個對話分別修改 .worktrees/login 與 .worktrees/cart；各自驗證、review 並 finish。`
+- Negative: `兩個對話同時修改主 checkout，彼此的寫入讓對方的驗證與 review 全部作廢。`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.2.8",
+  "version": "0.3.1",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "MIT",

package/schemas/config.schema.json

@@ -119,6 +119,41 @@
         }
       }
     },
+    "worktree": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode"],
+      "properties": {
+        "mode": {
+          "enum": ["auto", "off"]
+        },
+        "setup": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["command", "args"],
+            "properties": {
+              "command": {
+                "$ref": "#/$defs/nonEmptyString"
+              },
+              "args": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[^\\u0000]*$"
+                }
+              },
+              "timeoutMs": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 2147483647
+              }
+            }
+          }
+        }
+      }
+    },
     "securityExceptions": {
       "type": "array",
       "items": {