pi-anchorloop 2.3.0 → 2.4.0

package/README.md

@@ -25,10 +25,10 @@ shared           grilling · domain-modeling · human-feedback · agent-terse
 
 | File | What it does |
 | --- | --- |
-| `pi/book.ts` | The loop book. The first `todo` create or `kind` call opens a loop; task records need the `todo` tool of [`@juicesharp/rpiv-todo`](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo#readme) (its `tool_result` details `{tasks, nextId}` and `rpiv-todo-state` entries). The agent declares only what the extension cannot observe with `anchorloop_stage`: `kind` (`quick`, `inline`, `reviewed`, `durable`, with an intent and the anchor command; a later call changes the kind only with a `reason`), `verify` (a check not run in bash), `fresh-read`, `friction` (`tried`, `found`, `led_by`), `reflect`, `skip`, `back`, `close`, and the query `read`. Everything else is read from evidence: production edits (a write or edit in any git repo, outside its `scratch/` and `docs/specs/`; a linked child's edits and a successful `git merge`, `cherry-pick`, or `pull` count too), the exit code of the bash call that ran the anchor command (failed-then-passed runs become retry pairs), reviewer `Blocking: P0=<n> P1=<m>` counts, summaries of `docs/specs/*/` artifacts as they are edited, and a returned subagent that Jev judges to have been a fresh-context read of the spec. A phase machine over that evidence gives each kind a fixed sequence (`quick` act → check; `inline` anchor → act → verify; `reviewed` adds review; `durable` adds decide → grill → spec → read → approve → design; every kind ends with reflect → close), and `read` shows `<kind> · phase <current> ✓ → <next> (missing: …) · skipped: …`. An anchor run or declared verify of a `quick` or `inline` loop also measures the diff's reach: source files (not tests, lockfiles, specs, or prose), the top-level directories they sit in, and a README, changelog, or `*.schema.json` changed beside them. Files already changed when a repo joined the loop count only once their content changes, and a file at a repository root counts as a file, not a directory. At 3 source files, 2 directories, or one such file, the result carries one line asking to re-classify, and verify waits for a `kind` call with `reason` that answers each threshold crossed; a later threshold asks again. A phase that starts before an earlier one is complete warns once in one line and names the `skip` escape; phases regress when evidence changes or on `back`. The book also records each todo with its `anchor`, `ref` (`<path>#<heading>`, resolved to line ranges), and `followup` metadata. One YAML book per open loop lives under `~/.pi/agent/anchorloop/books/` (`ANCHORLOOP_BOOKS_DIR` overrides it; empty project and `agents/` directories are removed), subagent books under `agents/` (a child that closes keeps its book for the main session); `session_start` sweeps books whose session is gone or that have not changed in 7 days. `close` lists every phase as done, skipped, or auto-skipped and never refuses over phases or friction, only while a pending or in-progress todo lacks `metadata.followup` (a ticket id, `memory`, or `drop — <reason>`). |
+| `pi/book.ts` | The loop book. The first `todo` create or `kind` call opens a loop; task records need the `todo` tool of [`@juicesharp/rpiv-todo`](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo#readme) (its `tool_result` details `{tasks, nextId}` and `rpiv-todo-state` entries). The agent declares only what the extension cannot observe with `anchorloop_stage`: `kind` (`quick`, `inline`, `reviewed`, `durable`, with an intent and the anchor command; a later call changes the kind only with a `reason`), `verify` (a check not run in bash), `fresh-read`, `friction` (`tried`, `found`, `led_by`), `reflect`, `skip`, `back`, `close`, and the query `read`. Everything else is read from evidence: production edits (a write or edit in any git repo, outside its `scratch/` and `docs/specs/`; a linked child's edits and a successful `git merge`, `cherry-pick`, or `pull` count too), the exit code of the bash call that ran the anchor command (an anchor that passed, failed, and passed again records its own friction entry: the rerun command and the failed run's key line, at most 120 characters and never a stack trace, still waiting for a `reflect`), reviewer `Blocking: P0=<n> P1=<m>` counts, summaries of `docs/specs/*/` artifacts as they are edited, and a returned subagent that Jev judges to have been a fresh-context read of the spec. A phase machine over that evidence gives each kind a fixed sequence (`quick` act → check; `inline` anchor → act → verify; `reviewed` adds review; `durable` adds decide → grill → spec → read → approve → design; every kind ends with reflect → close), and `read` shows `<kind> · phase <current> ✓ → <next> (missing: …) · skipped: …`. The pi footer shows `anchorloop <kind> · <current> ✓ → <next>`, with the friction still to reflect, after every tool call and on `session_start`, and clears when the loop closes. An anchor run or declared verify of a `quick` or `inline` loop also measures the diff's reach: source files (not tests, lockfiles, specs, or prose), the top-level directories they sit in, and a README, changelog, or `*.schema.json` changed beside them. Files already changed when a repo joined the loop count only once their content changes, and a file at a repository root counts as a file, not a directory. At 3 source files, 2 directories, or one such file, the result carries one line asking to re-classify, and verify waits for a `kind` call with `reason` that answers each threshold crossed; a later threshold asks again. A phase that starts before an earlier one is complete warns once in one line and names the `skip` escape; phases regress when evidence changes or on `back`. The book also records each todo with its `anchor`, `ref` (`<path>#<heading>`, resolved to line ranges), and `followup` metadata. One YAML book per open loop lives under `~/.pi/agent/anchorloop/books/` (`ANCHORLOOP_BOOKS_DIR` overrides it; empty project and `agents/` directories are removed), subagent books under `agents/` (a child that closes keeps its book for the main session); `session_start` sweeps books whose session is gone or that have not changed in 7 days. `close` lists every phase as done, skipped, or auto-skipped and never refuses over phases or friction, only while a pending or in-progress todo lacks `metadata.followup` (a ticket id, `memory`, or `drop — <reason>`). |
 | `pi/anchor-gate.ts` | Inside an open loop, shows one warning line when `write` or `edit` starts the `act` phase while an earlier phase of the loop kind is incomplete: no anchor (`anchor` on the `kind` call, a `Reality anchor:` line, or a skip), and in a `durable` loop a missing decision, spec, fresh read, approval, or design, read from the `docs/specs/<folder>/` files (found from the book, the intent, or a todo `ref`). It warns again only when a new phase goes missing; the call still goes through. Outside a loop and in `quick` loops it stays silent. `.md`, `.txt`, and `.html` files, `scratch/`, `docs/specs/`, and temp files outside the project pass silently. Edits made through `bash` are not checked. |
 | `pi/decision-tool.ts` | The `anchorloop_decision` tool appends single-line, spreadsheet-safe rows to a decision trail TSV, or a `start` row when a run picks up another run's trail. |
-| `pi/second-thought.ts` | Inside an open loop, asks Jev (TypeSafe's typed-decision model, through pi's classifier registry) to check the phase machine when a run settles and the loop book gained an entry since the last judgment, and at a `close` declaration. The program computes the next phase from the book; Jev sees the kind, intent, anchor, diff summary (≤1200 chars), `phase` (current, next, missing), verify state, open todos, the task list, and friction (a child's under its name), and judges only whether to `advance`, go `back`, or `ask-user`, plus `done`, the review tier still needed, and quality; phase completion comes from the program's evidence alone. The one-line advisory leads with `next → <phase>`; a retry pair with no friction entry adds a `friction` hint. The run continues once, only when Jev agrees to advance and the next phase is a verify, review, or fix; an advisory identical to the last one is not repeated, and a `full` rating after a clean review that follows the last change shows a note instead of a recheck. A run that called `MonitorCreate`, `LoopCreate`, `goal_wait`, or a `subagent` tool is waiting and is not judged. Without a TypeSafe key it does nothing, and outside a loop it never runs. In a subagent session (`PI_SUBAGENT_ID` from pi-herdr-agents, or `PI_SUBAGENT_CHILD` from pi-subagents) it registers nothing, since the agent that spawned it judges the result. |
+| `pi/second-thought.ts` | Inside an open loop, asks Jev (TypeSafe's typed-decision model, through pi's classifier registry) to check the phase machine when a run settles and the loop book gained an entry since the last judgment, and at a `close` declaration. The program computes the next phase from the book; Jev sees the kind, intent, anchor, diff summary (≤1200 chars), `phase` (current, next, missing), verify state, open todos, the task list, and friction (a child's under its name), and judges only whether to `advance`, go `back`, or `ask-user`, plus `done`, the review tier still needed, and quality; phase completion comes from the program's evidence alone. The one-line advisory leads with `next → <phase>`. The run continues once, only when Jev agrees to advance and the next phase is a verify, review, or fix; an advisory identical to the last one is not repeated, and a `full` rating after a clean review that follows the last change shows a note instead of a recheck. A run that called `MonitorCreate`, `LoopCreate`, `goal_wait`, or a `subagent` tool is waiting and is not judged. Without a TypeSafe key it does nothing, and outside a loop it never runs. In a subagent session (`PI_SUBAGENT_ID` from pi-herdr-agents, or `PI_SUBAGENT_CHILD` from pi-subagents) it registers nothing, since the agent that spawned it judges the result. |
 | `pi/validate-tool-use.ts` | After each `write` or `edit`, validates the file in-process (`pi/support/validators.ts`, a port of `hooks/validators/`) and appends suggestions for `SKILL.md`, instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `rules/`), and `docs/specs/` artifacts. Needs no Python; the Python validators in `hooks/` remain for `validate_all.py` and the parity test. |
 | `pi/ttsr.ts` | A port of oh-my-pi's Time Traveling Stream Rules. A Markdown rule in `~/.pi/agent/rules/` or `<project>/.pi/rules/` whose frontmatter has a `condition` regex is watched during the run. A match in streamed assistant text aborts the response, drops it, and retries with the rule injected; a match in tool arguments (the command for `bash`, the new text for `write` and `edit`) blocks the call with the rule as its reason. Frontmatter fields follow oh-my-pi: `condition`, `scope` (`text`, `thinking`, `tool`, `tool:bash`, `tool:edit(*.ts)`), `globs`, and `interruptMode` (`always`, `prose-only`, `tool-only`, `never`), plus `repeatMode` (`once` or `after-gap`) and `repeatGap`. A rule fires once per session by default. `astCondition`, `question`, and `agents` are not supported; a rule that uses them is skipped and reported. `/ttsr` lists the loaded rules. |
 

package/README.zh-TW.md

@@ -25,10 +25,10 @@ anchorloop            核心循環 · 原則 · playbook：autonomous-run、paus
 
 | 檔案 | 作用 |
 | --- | --- |
-| `pi/book.ts` | Loop book。第一次 `todo` create 或 `kind` 呼叫會開啟一個 loop；任務紀錄需要 [`@juicesharp/rpiv-todo`](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo#readme) 的 `todo` 工具（它的 `tool_result` details `{tasks, nextId}` 和 `rpiv-todo-state` 條目）。agent 只用 `anchorloop_stage` 宣告 extension 看不到的事：`kind`（`quick`、`inline`、`reviewed`、`durable`，附 intent 和 anchor 指令；之後要改種類，必須附 `reason`）、`verify`（不是指令的檢查）、`fresh-read`、`friction`（`tried`、`found`、`led_by`）、`reflect`、`skip`、`back`、`close`，以及查詢用的 `read`。其餘都從證據讀出：production 的修改（任何 git repo 內、`scratch/` 與 `docs/specs/` 以外的 write 或 edit；已連結 child 的修改，以及成功的 `git merge`、`cherry-pick`、`pull` 也算）、執行過 anchor 指令的那次 bash 的 exit code（失敗後又通過的執行會成為 retry pair）、reviewer 的 `Blocking: P0=<n> P1=<m>` 數字、`docs/specs/*/` 產出物每次編輯後的摘要，以及 Jev 判定為「全新 context 讀過 spec」的 subagent 回報。階段機依這些證據給每種 loop 固定的階段順序（`quick` 為 act → check；`inline` 為 anchor → act → verify；`reviewed` 加 review；`durable` 再加 decide → grill → spec → read → approve → design；每一種都以 reflect → close 結尾），`read` 顯示 `<種類> · phase <目前> ✓ → <下一個>（缺：…）· 已跳過：…`。`quick` 或 `inline` loop 跑 anchor 或宣告 verify 時，也會量 diff 的影響範圍：原始碼檔案（不含測試、lockfile、spec 與文字檔）、它們所在的頂層目錄，以及跟原始碼一起改的 README、changelog 或 `*.schema.json`。repo 加入 loop 時就已經改過的檔案，要等內容再變動才算；repo 根目錄的檔案只算檔案數，不算一個目錄。達到 3 個原始碼檔案、2 個目錄或 1 個這類檔案時，結果會附一行請 agent 重新分類；verify 要等到以 `reason` 呼叫 `kind`、回應每一個跨過的門檻才算完成，之後再跨過新的門檻會再問一次。前一個階段還沒完成就開始下一個階段，會用一行警告一次並指出 `skip` 的出口；證據改變或用 `back` 時階段會退回。book 也記錄每個 todo 的 `anchor`、`ref`（`<path>#<heading>`，解析成行號範圍）和 `followup` metadata。每個開啟中的 loop 有一份 YAML book，放在 `~/.pi/agent/anchorloop/books/`（可用 `ANCHORLOOP_BOOKS_DIR` 覆寫），subagent 的 book 放在 `agents/`（subagent 自己 close 時 book 留給主 session）；`session_start` 會清掉 session 已不存在或 7 天沒有更新的 book。`close` 不會因為階段或 friction 而拒絕，只在還有 pending 或 in-progress 的 todo 沒有 `metadata.followup`（票號、`memory` 或 `drop — <原因>`）時拒絕。 |
+| `pi/book.ts` | Loop book。第一次 `todo` create 或 `kind` 呼叫會開啟一個 loop；任務紀錄需要 [`@juicesharp/rpiv-todo`](https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo#readme) 的 `todo` 工具（它的 `tool_result` details `{tasks, nextId}` 和 `rpiv-todo-state` 條目）。agent 只用 `anchorloop_stage` 宣告 extension 看不到的事：`kind`（`quick`、`inline`、`reviewed`、`durable`，附 intent 和 anchor 指令；之後要改種類，必須附 `reason`）、`verify`（不是指令的檢查）、`fresh-read`、`friction`（`tried`、`found`、`led_by`）、`reflect`、`skip`、`back`、`close`，以及查詢用的 `read`。其餘都從證據讀出：production 的修改（任何 git repo 內、`scratch/` 與 `docs/specs/` 以外的 write 或 edit；已連結 child 的修改，以及成功的 `git merge`、`cherry-pick`、`pull` 也算）、執行過 anchor 指令的那次 bash 的 exit code（anchor 通過後失敗、又再通過時，extension 會自己記一筆 friction：重跑的指令，加上失敗那次最關鍵的一行輸出，最多 120 字元，不放 stack trace；這筆仍要 `reflect` 分類）、reviewer 的 `Blocking: P0=<n> P1=<m>` 數字、`docs/specs/*/` 產出物每次編輯後的摘要，以及 Jev 判定為「全新 context 讀過 spec」的 subagent 回報。階段機依這些證據給每種 loop 固定的階段順序（`quick` 為 act → check；`inline` 為 anchor → act → verify；`reviewed` 加 review；`durable` 再加 decide → grill → spec → read → approve → design；每一種都以 reflect → close 結尾），`read` 顯示 `<種類> · phase <目前> ✓ → <下一個>（缺：…）· 已跳過：…`。pi 的 footer 會顯示 `anchorloop <種類> · <目前> ✓ → <下一個>`，以及還沒 reflect 的 friction 數；每次工具呼叫後和 `session_start` 時更新，loop 結案後清掉。`quick` 或 `inline` loop 跑 anchor 或宣告 verify 時，也會量 diff 的影響範圍：原始碼檔案（不含測試、lockfile、spec 與文字檔）、它們所在的頂層目錄，以及跟原始碼一起改的 README、changelog 或 `*.schema.json`。repo 加入 loop 時就已經改過的檔案，要等內容再變動才算；repo 根目錄的檔案只算檔案數，不算一個目錄。達到 3 個原始碼檔案、2 個目錄或 1 個這類檔案時，結果會附一行請 agent 重新分類；verify 要等到以 `reason` 呼叫 `kind`、回應每一個跨過的門檻才算完成，之後再跨過新的門檻會再問一次。前一個階段還沒完成就開始下一個階段，會用一行警告一次並指出 `skip` 的出口；證據改變或用 `back` 時階段會退回。book 也記錄每個 todo 的 `anchor`、`ref`（`<path>#<heading>`，解析成行號範圍）和 `followup` metadata。每個開啟中的 loop 有一份 YAML book，放在 `~/.pi/agent/anchorloop/books/`（可用 `ANCHORLOOP_BOOKS_DIR` 覆寫），subagent 的 book 放在 `agents/`（subagent 自己 close 時 book 留給主 session）；`session_start` 會清掉 session 已不存在或 7 天沒有更新的 book。`close` 不會因為階段或 friction 而拒絕，只在還有 pending 或 in-progress 的 todo 沒有 `metadata.followup`（票號、`memory` 或 `drop — <原因>`）時拒絕。 |
 | `pi/anchor-gate.ts` | 只在開啟的 loop 內：`write` 或 `edit` 開始 `act` 階段、而這種 loop 前面的階段還沒完成時，顯示一行警告：沒有 anchor（kind 呼叫的 `anchor`、`Reality anchor:` 這一行，或已跳過），`durable` loop 則還缺決策、spec、全新 context 的閱讀、核准或設計（從 `docs/specs/<資料夾>/` 的檔案判斷，資料夾由 book、intent 或 todo 的 `ref` 找出）。只有新缺了一個階段時才會再警告；呼叫仍會放行。沒有 loop 或是 `quick` loop 時保持安靜。`.md`、`.txt`、`.html` 檔、`scratch/`、`docs/specs/` 和專案外的暫存檔不會觸發。透過 `bash` 做的修改不檢查。 |
 | `pi/decision-tool.ts` | `anchorloop_decision` 工具把一筆決策寫進 TSV 決策軌跡，每筆只佔一行，用試算表開啟也安全；接手別人的軌跡時寫一筆 `start`。 |
-| `pi/second-thought.ts` | 只在開啟的 loop 內：一次執行結束且 book 自上次判斷後多了條目時，以及宣告 `close` 時，透過 pi 的 classifier registry 請 Jev（TypeSafe 的型別化決策模型）複核階段機。下一個階段由程式從 book 算出；Jev 看到種類、intent、anchor、diff 摘要（≤1200 字元）、`phase`（目前、下一個、缺什麼）、verify 狀態、未完成 todo、任務清單和 friction（子 agent 的以它的名字列出），只判斷要 `advance`、退回（`back`）還是 `ask-user`，另外還問 `done`、還需要哪一級 review 與品質；階段是否完成只由程式依證據判定。一行提醒以 `next → <階段>` 開頭；有 retry pair 卻沒有 friction 條目時，附上 `friction` 提示。只有 Jev 同意前進、而下一個階段是 verify、review 或 fix 時，才讓 agent 多跑一輪；與上一則相同的提醒不重複，最後一次修改之後已有無 blocking 發現的 review 時，`full` 評等只顯示備註、不要求複查。呼叫過 `MonitorCreate`、`LoopCreate`、`goal_wait` 或 `subagent` 工具的執行在等待中，不被判斷。沒有 TypeSafe key 時什麼都不做，沒有 loop 時不會執行。subagent session（pi-herdr-agents 的 `PI_SUBAGENT_ID`，或 pi-subagents 的 `PI_SUBAGENT_CHILD`）不註冊任何東西，因為由派它的 agent 判斷結果。 |
+| `pi/second-thought.ts` | 只在開啟的 loop 內：一次執行結束且 book 自上次判斷後多了條目時，以及宣告 `close` 時，透過 pi 的 classifier registry 請 Jev（TypeSafe 的型別化決策模型）複核階段機。下一個階段由程式從 book 算出；Jev 看到種類、intent、anchor、diff 摘要（≤1200 字元）、`phase`（目前、下一個、缺什麼）、verify 狀態、未完成 todo、任務清單和 friction（子 agent 的以它的名字列出），只判斷要 `advance`、退回（`back`）還是 `ask-user`，另外還問 `done`、還需要哪一級 review 與品質；階段是否完成只由程式依證據判定。一行提醒以 `next → <階段>` 開頭。只有 Jev 同意前進、而下一個階段是 verify、review 或 fix 時，才讓 agent 多跑一輪；與上一則相同的提醒不重複，最後一次修改之後已有無 blocking 發現的 review 時，`full` 評等只顯示備註、不要求複查。呼叫過 `MonitorCreate`、`LoopCreate`、`goal_wait` 或 `subagent` 工具的執行在等待中，不被判斷。沒有 TypeSafe key 時什麼都不做，沒有 loop 時不會執行。subagent session（pi-herdr-agents 的 `PI_SUBAGENT_ID`，或 pi-subagents 的 `PI_SUBAGENT_CHILD`）不註冊任何東西，因為由派它的 agent 判斷結果。 |
 | `pi/validate-tool-use.ts` | 每次 `write` 或 `edit` 後在行程內驗證該檔（`pi/support/validators.ts`，移植自 `hooks/validators/`），替 `SKILL.md`、指令檔（`AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`rules/`）和 `docs/specs/` 產出物附上建議。不需要 Python；`hooks/` 的 Python 驗證器仍供 `validate_all.py` 和對照測試使用。 |
 | `pi/ttsr.ts` | 移植自 oh-my-pi 的 Time Traveling Stream Rules。`~/.pi/agent/rules/` 或 `<專案>/.pi/rules/` 裡 frontmatter 帶有 `condition` regex 的 Markdown 規則，會在執行過程中被監看。assistant 串流文字命中時，中斷回應、丟棄那段輸出，並注入規則後重試；工具參數命中時（`bash` 看指令，`write`／`edit` 看新寫入的文字），直接擋下呼叫，以規則內容作為理由。frontmatter 欄位沿用 oh-my-pi：`condition`、`scope`（`text`、`thinking`、`tool`、`tool:bash`、`tool:edit(*.ts)`）、`globs`、`interruptMode`（`always`、`prose-only`、`tool-only`、`never`），另加 `repeatMode`（`once` 或 `after-gap`）與 `repeatGap`。預設每條規則每個 session 只觸發一次。不支援 `astCondition`、`question`、`agents`，用到的規則會被跳過並回報。`/ttsr` 列出已載入的規則。 |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-anchorloop",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Agent workflow skills for pi: one entry skill per task type, each with playbooks, over a shared Align → Anchor → Act → Verify loop, plus loop extensions (loop book, anchor gate, decision trail tool, Jev second thought, skill validator, stream rules).",
   "author": "Wei Hung",
   "license": "MIT",

package/pi/book.ts

@@ -35,6 +35,7 @@ import {
 	openLoop,
 	replayTodos,
 	refsOf,
+	retryPairs,
 	resolveRef,
 	reviewTrend,
 	reviews,
@@ -98,6 +99,38 @@ function textOf(content: unknown): string {
 	return (content as Block[]).map((block) => (block && typeof block.text === "string" ? block.text : "")).filter(Boolean).join("\n");
 }
 
+/** `text` cut to `limit` characters, the cut marked. */
+function clip(text: string, limit = 120): string {
+	return text.length <= limit ? text : `${text.slice(0, limit - 1)}…`;
+}
+
+const ANSI = /\x1b\[[0-9;]*[A-Za-z]/g;
+// Stack frames and traceback headers say where, not what; the key line says what failed.
+const FRAME = /^(?:at\s|File\s"|Traceback\b|\^+$)/;
+const KEY_LINES = [
+	/^(?:FAILED|ERROR)\b/,
+	/^E\s+\S/,
+	/^[\w.]+(?:Error|Exception|Warning)\b:?/,
+	/\b(?:error|fatal|panic|exception)\b/i,
+	/\bfail(?:ed|ure|s)?\b/i,
+];
+
+/** The one line of a failed run's output that says what failed, at most 120 characters; the last line when none does. */
+function keyLine(text: string): string {
+	const raw = text.replace(ANSI, "").split("\n");
+	// A Python frame's next line, indented under it, is the source it quotes, not the failure.
+	const quoted = (index: number) => /^\s/.test(raw[index]) && /^\s*File\s"/.test(raw[index - 1] ?? "");
+	const lines = raw.flatMap((line, index) => {
+		const trimmed = line.trim();
+		return trimmed && !FRAME.test(trimmed) && !quoted(index) ? [trimmed] : [];
+	});
+	for (const pattern of KEY_LINES) {
+		const hit = lines.find((line) => pattern.test(line));
+		if (hit) return clip(hit);
+	}
+	return clip(lines.at(-1) ?? "");
+}
+
 function lastLine(text: string): string {
 	return (
 		text
@@ -297,6 +330,8 @@ function statedAnchor(message: { role?: string; content?: unknown } | undefined)
 	return found ? found[1].trim().slice(0, 300) || "(stated on the next line)" : undefined;
 }
 
+const STATUS_KEY = "anchorloop";
+
 const reply = (text: string) => ({ content: [{ type: "text" as const, text }], details: undefined });
 
 export default function (pi: ExtensionAPI) {
@@ -328,7 +363,6 @@ export default function (pi: ExtensionAPI) {
 			`reviews: ${reviewTrend(book.entries)}; open todos: ${open}; friction: ${friction.length} (${friction.filter((item) => !item.reflected).length} unreflected)`,
 			...childLines(book.entries).map((line) => `child ${line}`),
 			...friction.filter((item) => item.owner !== "main").map((item) => `friction ${item.ref}: ${item.tried} → ${item.found}${item.reflected ? ` [${item.class}]` : ""}`),
-			...phases.hints,
 			...freshReadLine(book, phases),
 		];
 	}
@@ -463,88 +497,96 @@ export default function (pi: ExtensionAPI) {
 			required: ["stage"],
 			additionalProperties: false,
 		},
-		async execute(_toolCallId: string, raw: unknown, _signal: unknown, _onUpdate: unknown, ctx: ExtensionContext) {
-			const params = raw as Params;
-			const { stage } = params;
-			if (!(STAGES as readonly string[]).includes(stage)) throw new Error(`unknown stage \`${String(stage)}\`; declare one of ${STAGES.join(", ")}`);
-			let book = openLoop(ctx);
-			if (!book && stage === "kind") {
-				// A todo create in the same batch may not have landed yet; whichever comes first opens the loop.
-				if (!params.kind || !params.intent) throw new Error("the first kind declaration needs `kind` and a one-line `intent`");
-				book = createBook(ctx);
-				recordPriorAnchor(book, ctx);
-			}
-			if (!book) return reply("No loop is open, so nothing was recorded. A loop opens with the first `todo` create or `kind`.");
-			const had = currentKind(book.entries);
-			const sequence = SEQUENCES[had ?? "inline"];
-			if (stage === "read") {
-				const lines = [...summaryLines(book, ctx), ...taskLines(book.entries, todosOf(ctx), ctx.cwd)];
-				if (params.view === "all") lines.push("entries:", ...book.entries.map((entry) => JSON.stringify(entry).slice(0, 300)));
-				return reply(lines.join("\n"));
-			}
-			if (stage === "close") {
-				if (!params.verdict) throw new Error("close needs a verdict: landed, blocked, or abandoned");
-				const closed = close(book, ctx, params.verdict);
-				return { content: [{ type: "text" as const, text: closed.text }], details: closed.snapshot ? { snapshot: closed.snapshot } : undefined };
-			}
-			if (stage === "kind") {
-				if (!params.kind && !params.intent && !params.anchor && !params.reason) throw new Error("kind needs `kind`, `intent`, `anchor`, or `reason`");
-				if (!had && (!params.kind || !params.intent)) throw new Error("the first kind declaration needs `kind` and a one-line `intent`");
-				const changed = had !== undefined && params.kind !== undefined && had !== params.kind;
-				if (changed && !params.reason) throw new Error(`changing the kind from ${had} to ${params.kind} needs \`reason\`: the reach grew, the user added scope, a user-owned decision appeared, or the change turned out smaller`);
-				touchRepo(book, join(ctx.cwd, "_"));
-				const notes: string[] = [];
-				if (params.kind || params.intent || params.reason) {
-					// A reason answers the reach measured now, so a later threshold asks again.
-					const answer = params.reason ? { reason: params.reason, crossed: reachOf(book.entries, ctx.cwd).crossed } : {};
-					appendEntry(book.path, "kind", { kind: params.kind ?? had, ...(params.intent ? { intent: params.intent } : {}), ...answer });
-					const why = params.reason ? ` (${params.reason})` : "";
-					notes.push(changed ? `kind changed: ${had} → ${params.kind}${why}` : `kind: ${params.kind ?? had}${why}`);
-				}
-				if (params.anchor) {
-					appendEntry(book.path, "anchor", { check: params.anchor });
-					notes.push(`anchor: ${params.anchor}`);
-				}
-				return reply(notes.join("\n"));
-			}
-			if (stage === "verify") {
-				if (!params.note) throw new Error("verify needs a `note` saying what was observed");
-				const result = params.result ?? "pass";
-				const recorded = childId() !== undefined || had === "quick" ? "check" : "verify";
-				const entry = appendEntry(book.path, recorded, { declared: true, note: params.note, result, exit: result === "pass" ? 0 : 1, ...reachField(book, ctx.cwd) });
-				book.entries.push(entry);
-				const notice = reachNotice(book, entry);
-				return reply(`${recorded} declared: ${result} — ${params.note}${notice ? `\n${notice}` : ""}`);
-			}
-			if (stage === "fresh-read") {
-				appendEntry(book.path, "goldfish", { source: "declared", ...(params.note ? { note: params.note } : {}) });
-				return reply("fresh-read recorded.");
-			}
-			if (stage === "friction") {
-				if (!params.tried || !params.found) throw new Error("friction needs `tried` and `found`");
-				const id = frictionOf(book.entries).length + 1;
-				appendEntry(book.path, "friction", { id, tried: params.tried, found: params.found, led_by: params.led_by || "none" });
-				return reply(`friction #${id} recorded.`);
-			}
-			if (stage === "reflect") {
-				const known = allFriction(book.entries).map((item) => item.ref);
-				const ids = (params.friction ?? []).map(String);
-				if (ids.length === 0 || !params.class) throw new Error(`reflect needs \`friction\` ids (${known.join(", ") || "none recorded"}) and \`class\``);
-				const unknown = ids.filter((id) => !known.includes(id));
-				if (unknown.length) throw new Error(`unknown friction ${unknown.join(", ")}; known: ${known.join(", ") || "none"}`);
-				appendEntry(book.path, "reflect", { friction: ids, class: params.class, ...(params.action ? { action: params.action } : {}) });
-				return reply(`reflect recorded for ${ids.join(", ")} (${params.class}).`);
+		async execute(toolCallId: string, raw: unknown, signal: unknown, onUpdate: unknown, ctx: ExtensionContext) {
+			try {
+				return await stageTool(toolCallId, raw, signal, onUpdate, ctx);
+			} finally {
+				guarded(showStatus)(ctx);
 			}
-			// skip and back
-			const phase = params.phase;
-			const known = sequence.filter((name) => name !== "close");
-			if (!phase || !known.includes(phase)) throw new Error(`${stage} needs \`phase\`, one of ${known.join(", ")} for a ${had ?? "undeclared"} loop`);
-			if (!params.reason) throw new Error(`${stage} needs a \`reason\``);
-			appendEntry(book.path, stage, { phase, reason: params.reason });
-			return reply(stage === "skip" ? `${phase}: skipped (${params.reason}).` : `back to ${phase} (${params.reason}); later phases count as incomplete until their conditions hold again.`);
 		},
 	});
 
+	async function stageTool(_toolCallId: string, raw: unknown, _signal: unknown, _onUpdate: unknown, ctx: ExtensionContext) {
+		const params = raw as Params;
+		const { stage } = params;
+		if (!(STAGES as readonly string[]).includes(stage)) throw new Error(`unknown stage \`${String(stage)}\`; declare one of ${STAGES.join(", ")}`);
+		let book = openLoop(ctx);
+		if (!book && stage === "kind") {
+			// A todo create in the same batch may not have landed yet; whichever comes first opens the loop.
+			if (!params.kind || !params.intent) throw new Error("the first kind declaration needs `kind` and a one-line `intent`");
+			book = createBook(ctx);
+			recordPriorAnchor(book, ctx);
+		}
+		if (!book) return reply("No loop is open, so nothing was recorded. A loop opens with the first `todo` create or `kind`.");
+		const had = currentKind(book.entries);
+		const sequence = SEQUENCES[had ?? "inline"];
+		if (stage === "read") {
+			const lines = [...summaryLines(book, ctx), ...taskLines(book.entries, todosOf(ctx), ctx.cwd)];
+			if (params.view === "all") lines.push("entries:", ...book.entries.map((entry) => JSON.stringify(entry).slice(0, 300)));
+			return reply(lines.join("\n"));
+		}
+		if (stage === "close") {
+			if (!params.verdict) throw new Error("close needs a verdict: landed, blocked, or abandoned");
+			const closed = close(book, ctx, params.verdict);
+			return { content: [{ type: "text" as const, text: closed.text }], details: closed.snapshot ? { snapshot: closed.snapshot } : undefined };
+		}
+		if (stage === "kind") {
+			if (!params.kind && !params.intent && !params.anchor && !params.reason) throw new Error("kind needs `kind`, `intent`, `anchor`, or `reason`");
+			if (!had && (!params.kind || !params.intent)) throw new Error("the first kind declaration needs `kind` and a one-line `intent`");
+			const changed = had !== undefined && params.kind !== undefined && had !== params.kind;
+			if (changed && !params.reason) throw new Error(`changing the kind from ${had} to ${params.kind} needs \`reason\`: the reach grew, the user added scope, a user-owned decision appeared, or the change turned out smaller`);
+			touchRepo(book, join(ctx.cwd, "_"));
+			const notes: string[] = [];
+			if (params.kind || params.intent || params.reason) {
+				// A reason answers the reach measured now, so a later threshold asks again.
+				const answer = params.reason ? { reason: params.reason, crossed: reachOf(book.entries, ctx.cwd).crossed } : {};
+				appendEntry(book.path, "kind", { kind: params.kind ?? had, ...(params.intent ? { intent: params.intent } : {}), ...answer });
+				const why = params.reason ? ` (${params.reason})` : "";
+				notes.push(changed ? `kind changed: ${had} → ${params.kind}${why}` : `kind: ${params.kind ?? had}${why}`);
+			}
+			if (params.anchor) {
+				appendEntry(book.path, "anchor", { check: params.anchor });
+				notes.push(`anchor: ${params.anchor}`);
+			}
+			return reply(notes.join("\n"));
+		}
+		if (stage === "verify") {
+			if (!params.note) throw new Error("verify needs a `note` saying what was observed");
+			const result = params.result ?? "pass";
+			const recorded = childId() !== undefined || had === "quick" ? "check" : "verify";
+			const entry = appendEntry(book.path, recorded, { declared: true, note: params.note, result, exit: result === "pass" ? 0 : 1, ...reachField(book, ctx.cwd) });
+			book.entries.push(entry);
+			const notice = reachNotice(book, entry);
+			return reply(`${recorded} declared: ${result} — ${params.note}${notice ? `\n${notice}` : ""}`);
+		}
+		if (stage === "fresh-read") {
+			appendEntry(book.path, "goldfish", { source: "declared", ...(params.note ? { note: params.note } : {}) });
+			return reply("fresh-read recorded.");
+		}
+		if (stage === "friction") {
+			if (!params.tried || !params.found) throw new Error("friction needs `tried` and `found`");
+			const id = frictionOf(book.entries).length + 1;
+			appendEntry(book.path, "friction", { id, tried: params.tried, found: params.found, led_by: params.led_by || "none" });
+			return reply(`friction #${id} recorded.`);
+		}
+		if (stage === "reflect") {
+			const known = allFriction(book.entries).map((item) => item.ref);
+			const ids = (params.friction ?? []).map(String);
+			if (ids.length === 0 || !params.class) throw new Error(`reflect needs \`friction\` ids (${known.join(", ") || "none recorded"}) and \`class\``);
+			const unknown = ids.filter((id) => !known.includes(id));
+			if (unknown.length) throw new Error(`unknown friction ${unknown.join(", ")}; known: ${known.join(", ") || "none"}`);
+			appendEntry(book.path, "reflect", { friction: ids, class: params.class, ...(params.action ? { action: params.action } : {}) });
+			return reply(`reflect recorded for ${ids.join(", ")} (${params.class}).`);
+		}
+		// skip and back
+		const phase = params.phase;
+		const known = sequence.filter((name) => name !== "close");
+		if (!phase || !known.includes(phase)) throw new Error(`${stage} needs \`phase\`, one of ${known.join(", ")} for a ${had ?? "undeclared"} loop`);
+		if (!params.reason) throw new Error(`${stage} needs a \`reason\``);
+		appendEntry(book.path, stage, { phase, reason: params.reason });
+		return reply(stage === "skip" ? `${phase}: skipped (${params.reason}).` : `back to ${phase} (${params.reason}); later phases count as incomplete until their conditions hold again.`);
+	}
+
 	pi.on(
 		"session_start",
 		guarded((_event, ctx) => {
@@ -554,6 +596,7 @@ export default function (pi: ExtensionAPI) {
 				...swept.open.map((path) => `open loop book: ${path}`),
 			];
 			if (lines.length > 0) ctx.ui.notify(`anchorloop books\n${lines.join("\n")}`, "info");
+			showStatus(ctx);
 		}),
 	);
 
@@ -589,16 +632,23 @@ export default function (pi: ExtensionAPI) {
 		const exit = bashExit(event);
 		const last = lastLine(output);
 		const anchor = anchorCommand(book.entries);
-		let notice: string | undefined;
+		const notices: string[] = [];
+		// A failed run keeps its key line, so a rerun that passes can name what failed without the whole output.
+		const keyOf = (code: unknown) => (typeof code === "number" && code !== 0 ? { key: keyLine(output) } : {});
 		if (anchor && anchorRun(command, anchor)) {
 			const recorded = childId() !== undefined || currentKind(book.entries) === "quick" ? "check" : "verify";
-			const entry = appendEntry(book.path, recorded, { command: anchor.slice(0, 200), exit: anchorExit(command, anchor, exit), last, ...reachField(book, cwd) });
+			const code = anchorExit(command, anchor, exit);
+			const entry = appendEntry(book.path, recorded, { command: anchor.slice(0, 200), exit: code, last, ...keyOf(code), ...reachField(book, cwd) });
 			book.entries.push(entry);
-			notice = reachNotice(book, entry);
+			const reach = reachNotice(book, entry);
+			if (reach) notices.push(reach);
 		}
 		for (const task of latestTasks(book.entries)) {
-			if (typeof task.anchor === "string" && anchorRun(command, task.anchor)) appendEntry(book.path, "taskrun", { id: task.id, exit: anchorExit(command, task.anchor, exit), last });
+			if (typeof task.anchor !== "string" || !anchorRun(command, task.anchor)) continue;
+			const code = anchorExit(command, task.anchor, exit);
+			book.entries.push(appendEntry(book.path, "taskrun", { id: task.id, command: task.anchor.slice(0, 200), exit: code, last, ...keyOf(code) }));
 		}
+		notices.push(...autoFriction(book));
 		const merged = mergeRun(command);
 		if (exit === 0 && merged && !/Already up[ -]to[ -]date/i.test(last ?? "") && book.entries.at(-1)?.stage !== "edit") {
 			touchRepoBeforeMerge(book, resolve(String(book.header.cwd ?? process.cwd()), merged.dir), merged.verb);
@@ -608,7 +658,54 @@ export default function (pi: ExtensionAPI) {
 			const cwd = String(book.header.cwd ?? "");
 			if (diffAgainstBases(book.entries).paths.some((path) => !outsideWork(path, cwd))) appendEntry(book.path, "edit", { via: "commit" });
 		}
-		return notice;
+		return notices.join("\n") || undefined;
+	}
+
+	/**
+	 * Records one friction line for each anchor that passed again after it had passed and then failed. A pair is recorded
+	 * once, and not at all when the agent recorded a friction entry itself after the failure. The pairs one command
+	 * completes in one bash call (it is both the loop and a task anchor) share one entry. Returns the lines that tell the agent.
+	 */
+	function autoFriction(book: Book): string[] {
+		const lines: string[] = [];
+		const open = new Map<string, string[]>();
+		for (const pair of retryPairs(book.entries)) {
+			const id = `${pair.key}#${pair.fail}`;
+			const recorded = book.entries.some(
+				(entry, index) =>
+					entry.stage === "friction" && ((Array.isArray(entry.pairs) && entry.pairs.includes(id)) || (index > pair.fail && entry.auto !== true)),
+			);
+			if (recorded) continue;
+			const command = String(book.entries[pair.fail].command ?? pair.key);
+			open.set(command, [...(open.get(command) ?? []), id]);
+		}
+		for (const [command, pairs] of open) {
+			// The newest failure speaks for the entry; an older pair it backfills is listed in `pairs`.
+			const newest = pairs.at(-1) as string;
+			const failed = book.entries[Number(newest.slice(newest.lastIndexOf("#") + 1))];
+			const tried = clip(`rerun of ${command}`, 80);
+			// A failure recorded before 2.4 has no key line; its last line gets the same filter.
+			const found = clip(String(failed.key ?? keyLine(String(failed.last ?? ""))) || "failed with no output");
+			const number = frictionOf(book.entries).length + 1;
+			book.entries.push(appendEntry(book.path, "friction", { id: number, tried, found, led_by: "none", auto: true, pairs }));
+			lines.push(`anchorloop: friction #${number} recorded from the ${tried}: ${found}. Classify it with \`reflect\` before close.`);
+		}
+		return lines;
+	}
+
+	/** The footer line: the loop's kind, its last complete phase, the next one, and the friction still to reflect. */
+	function showStatus(ctx: ExtensionContext): void {
+		if (typeof ctx.ui?.setStatus !== "function") return;
+		const book = openLoop(ctx);
+		if (!book) {
+			ctx.ui.setStatus(STATUS_KEY, undefined);
+			return;
+		}
+		const phases = phasesOf(book, ctx);
+		const open = allFriction(book.entries).filter((item) => !item.reflected).length;
+		const kind = phases.kind === "undeclared" ? "no kind" : phases.kind;
+		const at = `${phases.current}${phases.current === "start" ? "" : " ✓"} → ${phases.next}`;
+		ctx.ui.setStatus(STATUS_KEY, `anchorloop ${kind} · ${at}${open ? ` · ${open} friction to reflect` : ""}`);
 	}
 
 	pi.on(
@@ -661,6 +758,14 @@ export default function (pi: ExtensionAPI) {
 		}),
 	);
 
+	// Registered after the recording handler, so the footer reads what that tool call just recorded.
+	pi.on(
+		"tool_result",
+		guarded((_event, ctx) => {
+			showStatus(ctx);
+		}),
+	);
+
 	async function recordReview(ctx: ExtensionContext, book: Book, name: string, text: string, failed: boolean): Promise<void> {
 		const counts = parseBlocking(text);
 		let blocking: boolean | null = null;

package/pi/second-thought.ts

@@ -106,7 +106,7 @@ export function continues(verdict: Verdict, snap: Snapshot): boolean {
 
 /** One line: the program's next phase and its gap, Jev's move and scores, and, away from close, the call to act. */
 export function message(verdict: Verdict, snap: Snapshot, found: string[], notes: string[], atClose = false): string {
-	const extra = [...found, ...notes, ...snap.hints];
+	const extra = [...found, ...notes];
 	return (
 		`Second thought (Jev, advisory): next → ${snap.next}${snap.missing ? ` (missing: ${snap.missing})` : ""}; ` +
 		`${verdict.move}; done ${verdict.done.toFixed(2)}, review ${verdict.review}, quality ${verdict.quality.toFixed(2)}/3` +

package/pi/support/book.ts

@@ -499,12 +499,6 @@ export function retryPairs(entries: Entry[]): RetryPair[] {
 	return pairs;
 }
 
-/** A retry pair that no friction entry follows. */
-export function retryWithoutFriction(entries: Entry[]): boolean {
-	const lastFriction = lastIndex(entries, "friction");
-	return retryPairs(entries).some((pair) => pair.pass > lastFriction);
-}
-
 // --- todos ---------------------------------------------------------------------------------------
 
 export type Task = { id: number; subject: string; status: string; metadata?: Record<string, unknown> };

package/pi/support/phases.ts

@@ -23,7 +23,6 @@ import {
 	lastActIndex,
 	lastIndex,
 	repoRootOf,
-	retryWithoutFriction,
 	specFolder,
 	withChildActs,
 } from "./book.ts";
@@ -47,8 +46,6 @@ export type Phases = {
 	missing: string;
 	skipped: string[];
 	backs: string[];
-	/** Advisory hints that are not phases. */
-	hints: string[];
 };
 
 export type Inputs = { entries: Entry[]; cwd: string; todos: Task[]; env?: NodeJS.ProcessEnv };
@@ -347,7 +344,6 @@ export function computePhases(book: Pick<Book, "entries">, inputs: Omit<Inputs,
 	if (next === "fix") note = first?.note ?? "";
 	const skipped = statuses.filter((status) => status.state === "skipped" && status.note !== "no friction").map((status) => `${status.name} (${status.note})`);
 	const backs = book.entries.filter((entry) => entry.stage === "back").map((entry) => `${entry.phase} (${entry.reason})`);
-	const hints = retryWithoutFriction(book.entries) ? ["friction: a failed run was retried and passed, with no friction entry after it"] : [];
 	return {
 		kind: kind ?? "undeclared",
 		statuses,
@@ -356,7 +352,6 @@ export function computePhases(book: Pick<Book, "entries">, inputs: Omit<Inputs,
 		missing: note,
 		skipped,
 		backs,
-		hints,
 	};
 }
 

package/pi/support/snapshot.ts

@@ -25,8 +25,6 @@ export type Snapshot = {
 	/** The program's next phase and what it lacks, in a few words. */
 	next: string;
 	missing: string;
-	/** Advisory hints that are not phases, such as an unrecorded friction. */
-	hints: string[];
 	/** The last phase the book shows complete. */
 	current: string;
 	/** A review recorded after the last change with no blocking finding on it. */
@@ -64,7 +62,6 @@ export function snapshot(book: Book, ctx: { cwd: string; sessionManager: { getBr
 		},
 		next: phases.next,
 		missing: phases.missing,
-		hints: phases.hints,
 		current: phases.current,
 		reviewClear: reviewClearAfterLastAct(entries),
 	};

package/skills/anchorloop/SKILL.md

@@ -29,7 +29,7 @@ The reply names a [principle](PRINCIPLES.md) only with the decision it changed.
 
 ### Friction Notes
 
-Each time an attempt fails and a later attempt reveals why, record it with `anchorloop_stage friction` before continuing.
+Each time an attempt fails and a later attempt reveals why, record it with `anchorloop_stage friction` before continuing. An anchor that passed, failed, and passed again is recorded by the extension; reflect on that entry like any other.
 
 ### Decision Trail