typeclaw 0.23.0 → 0.25.0

package/src/server/index.ts

@@ -11,12 +11,22 @@ import {
 import { runPluginDoctorChecks, runPluginDoctorFix } from '@/agent/doctor'
 import type { LiveSessionRegistry } from '@/agent/live-sessions'
 import type { LiveSubagentRegistry } from '@/agent/live-subagents'
+import { forgetSharedLoopGuardTool } from '@/agent/plugin-tools'
 import { detectProviderError } from '@/agent/provider-error'
 import { requestContainerRestart } from '@/agent/restart'
 import { consumeRestartHandoff, type RestartHandoff } from '@/agent/restart-handoff'
 import type { SessionOrigin } from '@/agent/session-origin'
 import { parseSubagentCompletedPayload, renderSubagentCompletionReminder } from '@/agent/subagent-completion-reminder'
 import type { CreateSessionForSubagent } from '@/agent/subagents'
+import { TODO_CONTINUATION_SOURCE } from '@/agent/todo/continuation'
+import {
+  armRestartKickForOrigin,
+  extractTurnUsage,
+  recordTurnOutcome,
+  recordTurnStart,
+  runIdleContinuation,
+} from '@/agent/todo/continuation-wiring'
+import { SUBAGENT_OUTPUT_TOOL_NAME } from '@/agent/tools/subagent-output'
 import type { ChannelRouter } from '@/channels/router'
 import { aggregateCronList, type CronListEntry, loadCron } from '@/cron'
 import type { McpManager } from '@/mcp'
@@ -155,6 +165,7 @@ type QueuedPrompt = {
   text: string
   delivery: PromptDelivery
   ts: number
+  source?: string
 }
 
 type SessionState = {
@@ -172,6 +183,7 @@ type SessionState = {
   // generation that ran session.start. A plugin reload mid-connection does
   // not re-target this session's lifecycle hooks.
   runtimeSnapshot: PluginRuntimeState | null
+  unsubTurnOutcome: Unsubscribe | null
   dispose: () => Promise<void>
 }
 
@@ -257,7 +269,7 @@ export function createServer({
       handoffPending = false
       return null
     }
-    handoffInFlight = consumeRestartHandoff(agentDir).catch(() => null)
+    handoffInFlight = consumeRestartHandoff(agentDir, { accept: (h) => h.origin.kind === 'tui' }).catch(() => null)
     const result = await handoffInFlight
     handoffPending = false
     handoffInFlight = null
@@ -497,6 +509,7 @@ export function createServer({
               unsubClaim: null,
               activeClaimCode: null,
               runtimeSnapshot: runtimeSnapshot ?? null,
+              unsubTurnOutcome: null,
               dispose,
             }
             sessionStates.set(ws, state)
@@ -505,12 +518,16 @@ export function createServer({
               await runtimeSnapshot.hooks.runSessionStart({ sessionId: sessionFileId, agentDir })
             }
 
+            if (agentDir !== undefined) {
+              state.unsubTurnOutcome = subscribeTurnOutcome(session, agentDir, origin, sessionFileId, logger)
+            }
+
             liveSessionRegistry?.register({ sessionId: sessionFileId, session })
             forwardSessionEvents(ws, session, logger, sessionFileId)
 
             if (stream) {
               state.unsubPrompts = stream.subscribe({ target: { kind: 'session', sessionId: sessionFileId } }, (msg) =>
-                enqueuePrompt(ws, state, msg, agentDir, logger),
+                enqueuePrompt(ws, state, msg, agentDir, logger, stream),
               )
 
               state.unsubBroadcast = stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
@@ -543,6 +560,17 @@ export function createServer({
             // wired (state.unsubPrompts above) so the kick is enqueued, not
             // dropped on the floor.
             if (resumed !== null && stream) {
+              // Arm the one-shot restart-kick suppressor BEFORE publishing the
+              // kick: the kick owns the first post-restart turn ("I'm back"),
+              // so the first idle after it must not also fire a todo
+              // continuation. The flag is consumed by that first idle. Best-
+              // effort: a failure here only risks one redundant nudge, which
+              // the episode budget still bounds.
+              if (agentDir !== undefined) {
+                await armRestartKickForOrigin(agentDir, origin).catch((err) =>
+                  logger.error(`[server] ${sessionFileId}: arm restart-kick suppression failed: ${describeErr(err)}`),
+                )
+              }
               stream.publish({
                 target: { kind: 'session', sessionId: sessionFileId },
                 payload: { kind: 'prompt', text: ' ', delivery: 'queue' },
@@ -798,6 +826,7 @@ export function createServer({
             }
           } finally {
             if (state) {
+              state.unsubTurnOutcome?.()
               state.session.dispose()
               await state.dispose()
               liveSessionRegistry?.unregister(state.sessionFileId)
@@ -867,6 +896,31 @@ function forwardSessionEvents(ws: Ws, session: AgentSession, logger: ServerLogge
   })
 }
 
+// Record each completed turn's stopReason for the todo-continuation guard.
+// Ordering-independent by design: this writes the outcome from `message_end`,
+// and the idle path only reads the stored outcome — it never assumes the
+// event arrived before idle fired. An unrecognized stopReason classifies as
+// 'unknown', which the idle path treats as not-safe-to-continue (fail closed).
+function subscribeTurnOutcome(
+  session: AgentSession,
+  agentDir: string,
+  origin: SessionOrigin,
+  sessionFileId: string,
+  logger: ServerLogger,
+): Unsubscribe {
+  return session.subscribe((event) => {
+    const usage = extractTurnUsage(event)
+    if (usage === null) return
+    void recordTurnOutcome({
+      agentDir,
+      origin,
+      turnId: sessionFileId,
+      stopReason: usage.stopReason,
+      ...(usage.tokens !== undefined ? { tokens: usage.tokens } : {}),
+    }).catch((err) => logger.error(`[server] ${sessionFileId}: todo outcome capture failed: ${describeErr(err)}`))
+  })
+}
+
 function forwardAssistantError(ws: Ws, message: unknown, logger: ServerLogger, sessionFileId: string): void {
   const detected = detectProviderError(message)
   if (detected === null) return
@@ -879,6 +933,12 @@ function routeSubagentCompletionReminder(state: SessionState, msg: StreamMessage
   if (parsed === null) return
   if (parsed.parentSessionId !== state.sessionFileId) return
 
+  // The reminder asks the agent to fetch this result now; clear the
+  // subagent_output window first so an earlier premature-polling streak can't
+  // hard-block that fetch. Reset before publish so the wakeup can't race stale
+  // guard state.
+  forgetSharedLoopGuardTool(state.sessionFileId, SUBAGENT_OUTPUT_TOOL_NAME)
+
   const idle = state.drainQueue.length === 0 && !state.draining
   const delivery = idle ? 'interrupt' : 'queue'
   const text = renderSubagentCompletionReminder(parsed)
@@ -895,6 +955,7 @@ function enqueuePrompt(
   msg: StreamMessage,
   agentDir: string | undefined,
   logger: ServerLogger,
+  stream: Stream | undefined,
 ): void {
   const payload = msg.payload as { kind?: string; text?: string; delivery?: PromptDelivery }
   if (payload?.kind !== 'prompt' || typeof payload.text !== 'string') return
@@ -904,14 +965,16 @@ function enqueuePrompt(
       send(ws, { type: 'error', message: err instanceof Error ? err.message : String(err) })
     })
   }
+  const source = (msg.meta as { source?: unknown } | undefined)?.source
   state.drainQueue.push({
     streamMessageId: msg.id,
     text: payload.text,
     delivery,
     ts: msg.ts,
+    ...(typeof source === 'string' ? { source } : {}),
   })
   pushQueueState(ws, state)
-  void drain(ws, state, agentDir, logger)
+  void drain(ws, state, agentDir, logger, stream)
 }
 
 // `session.idle` semantically means "the agent finished a prompt and is now
@@ -948,7 +1011,13 @@ function makeTurnHookCallers(
   }
 }
 
-async function drain(ws: Ws, state: SessionState, agentDir: string | undefined, logger: ServerLogger): Promise<void> {
+async function drain(
+  ws: Ws,
+  state: SessionState,
+  agentDir: string | undefined,
+  logger: ServerLogger,
+  stream: Stream | undefined,
+): Promise<void> {
   if (state.draining) return
   state.draining = true
   const fireIdle = makeIdleHookCaller(state)
@@ -960,6 +1029,14 @@ async function drain(ws: Ws, state: SessionState, agentDir: string | undefined,
       pushQueueState(ws, state)
       send(ws, { type: 'prompt_started', messageId: item.streamMessageId, text: item.text })
 
+      if (agentDir !== undefined) {
+        await recordTurnStart({
+          agentDir,
+          origin: state.origin,
+          isRealUserTurn: item.source !== TODO_CONTINUATION_SOURCE,
+        }).catch((err) => logger.error(`[server] ${state.sessionFileId}: todo turn-start failed: ${describeErr(err)}`))
+      }
+
       await fireTurnStart(item.text)
       try {
         await state.session.prompt(`${renderTurnTimeAnchor()}\n\n${item.text}`)
@@ -971,12 +1048,57 @@ async function drain(ws: Ws, state: SessionState, agentDir: string | undefined,
       }
       await fireTurnEnd()
       await fireIdle()
+
+      // Idle-continuation runs INSIDE the loop and enqueues directly onto
+      // drainQueue (not via stream.publish). Publishing would re-enter drain()
+      // through the session subscriber while `state.draining` is still true, so
+      // the nested call would no-op and the continuation would stall until some
+      // unrelated event woke the loop again. Enqueuing here lets the same `while`
+      // consume it on the next iteration. Only fires when the queue is otherwise
+      // empty so a real user turn is never preempted by a continuation.
+      if (state.drainQueue.length === 0) {
+        await maybeContinueTodos(state, agentDir, logger)
+      }
     }
   } finally {
     state.draining = false
   }
 }
 
+// If incomplete todos remain and all guards pass, push a single continuation
+// prompt directly onto this session's drainQueue, tagged TODO_CONTINUATION_SOURCE
+// so the next drain iteration treats it as an injected (non-user) turn that does
+// not reset the episode budget. The enclosing drain loop consumes it; this never
+// calls drain() itself.
+async function maybeContinueTodos(
+  state: SessionState,
+  agentDir: string | undefined,
+  logger: ServerLogger,
+): Promise<void> {
+  if (agentDir === undefined) return
+  try {
+    await runIdleContinuation({
+      agentDir,
+      origin: state.origin,
+      deliver: (text) => {
+        state.drainQueue.push({
+          streamMessageId: `todo-continuation-${crypto.randomUUID()}` as StreamMessageId,
+          text,
+          delivery: 'queue',
+          ts: Date.now(),
+          source: TODO_CONTINUATION_SOURCE,
+        })
+      },
+    })
+  } catch (err) {
+    logger.error(`[server] ${state.sessionFileId}: todo continuation failed: ${describeErr(err)}`)
+  }
+}
+
+function describeErr(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
 function pushQueueState(ws: Ws, state: SessionState): void {
   const pending: QueueStateItem[] = state.drainQueue.map((q) => ({
     id: q.streamMessageId,

package/src/skills/typeclaw-channel-github/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-channel-github
-description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `github`, AND before composing replies to GitHub-originated inbounds, AND before opening new issues or PRs with `gh`, AND ALWAYS when you are asked to review a PR — whether the inbound says "requested your review on PR #N" / "requested a review from team @… on PR #N", or a human asks for a review in plain language in an issue/PR body or comment ("@bot review this", "can you take a look at #123"). On a review request you delegate the analysis to the `reviewer` subagent, which produces line-anchored findings, then you post them as an inline review via `gh api`. GitHub renders **real markdown** — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and `inline code` all render natively. Use rich markdown freely. GitHub cannot send file attachments via API — do not call `channel_send` with attachments on github chats. GitHub has no typing indicator. PR review threads use `thread` keyed on the root comment id; reply to a thread to stay in it, or omit `thread` to post a top-level issue/PR comment. When a review comment **you authored** gets addressed — the author pushed a fix or replied that resolves it — verify the fix at the PR's head SHA and then resolve the thread with the `resolveReviewThread` GraphQL mutation (see "Resolving review threads you authored" below); resolving is the close-out that tells the author the concern is settled. To open new issues or PRs use the `gh` CLI — `GH_TOKEN` is pre-set by the adapter. Read this skill before composing anything on GitHub.
+description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `github`, AND before composing replies to GitHub-originated inbounds, AND before opening new issues or PRs with `gh`, AND ALWAYS when you are asked to review a PR — whether the inbound says "requested your review on PR #N" / "requested a review from team @… on PR #N", or a human asks for a review in plain language in an issue/PR body or comment ("@bot review this", "can you take a look at #123"). On a review request you delegate the analysis to the `reviewer` subagent, which produces line-anchored findings, then you post them as an inline review via `gh api`. GitHub renders **real markdown** — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and `inline code` all render natively. Use rich markdown freely. GitHub cannot send file attachments via API — do not call `channel_send` with attachments on github chats. GitHub has no typing indicator. PR review threads use `thread` keyed on the root comment id; reply to a thread to stay in it, or omit `thread` to post a top-level issue/PR comment. When a review comment **you authored** gets addressed — the author pushed a fix or replied that resolves it — verify the fix at the PR's head SHA and then resolve the thread by acknowledging with `channel_reply({ …, resolve_review_thread: true })`, which resolves the thread before posting the reply (see "Resolving review threads you authored" below); resolving is the close-out that tells the author the concern is settled. To open new issues or PRs use the `gh` CLI — `GH_TOKEN` is pre-set by the adapter. Read this skill before composing anything on GitHub.
 ---
 
 GitHub renders normal Markdown in issues, PRs, discussions, and review comments. Use headings, lists, tables, fenced code blocks, links, and inline code when they improve clarity.
@@ -8,15 +8,33 @@ GitHub renders normal Markdown in issues, PRs, discussions, and review comments.
 - Do not send attachments on GitHub chats; the adapter rejects them.
 - There is no typing indicator.
 - For PR review threads, keep `thread` set to reply in-place. Omit `thread` for a top-level PR/issue comment.
-- When a review comment **you authored** has been addressed, resolve its thread — see "Resolving review threads you authored" below. The base principle is **whoever opened the thread closes it**: you resolve only the threads you started, never a human's.
+- When a review comment **you authored** has been addressed, resolve its thread by replying with `channel_reply({ …, resolve_review_thread: true })` — see "Resolving review threads you authored" below. The base principle is **whoever opened the thread closes it**: you resolve only the threads you started, never a human's (the runtime enforces this).
 
 ## Mid-turn status replies need `continue: true`
 
 A successful `channel_reply` ends your turn by default — the runtime stops the model right after the reply lands. That is correct for a final answer, but it will **silently truncate** a turn that still has work to do. If you post a status line like "Reviewing now, I'll be back with findings" and then expect to keep working (fetch the diff, spawn the reviewer, post the review) in the **same** turn, you must call `channel_reply({ text: "…", continue: true })`. Without `continue: true`, the turn ends at that status reply and the review never runs. Reserve `continue: true` for genuine multi-step turns; the final reply that wraps up the turn omits it.
 
+## Inbound triage — do this first, every time
+
+Before you pick an action, classify the inbound. Skipping this step is how a PR ends up with a "looks good" comment but no approval: the model pattern-matches on the prose ("they fixed it → resolve the thread") and never asks whether it owes the PR a formal review. Answer these in order; the **first** that matches decides your path. Do not skip ahead.
+
+1. **Is this a PR, and do I have an unresolved blocking obligation on it?** On any `pr:N` inbound, before anything else, check whether you owe this PR a verdict you have not yet landed. Check **both** signals below — checking only formal review state misses the very failure this gate exists to catch, because a prior block may never have become formal state:
+   - **Formal review state.** Run the step-1 re-review query in the PR review flow (`gh api --paginate --slurp /repos/owner/repo/pulls/<N>/reviews --jq '…'` filtered to `{CHANGES_REQUESTED, APPROVED}`). If your latest **blocking decision** is `CHANGES_REQUESTED`, you have a live sticky block.
+   - **Flat-comment blockers you authored.** A prior "request changes" may have been posted as a plain PR/issue comment instead of a formal review — in which case **no `CHANGES_REQUESTED` row exists** and the query above returns empty even though you blocked the PR in prose. So also scan your own recent comments (`gh api /repos/owner/repo/issues/<N>/comments --jq '[.[] | select(.user.login == "<your-login>")]'`) for one that requested changes / raised blockers and has not since been superseded by a formal review or a clear retraction. For routing, a blocking comment you wrote is as binding as a formal `CHANGES_REQUESTED`.
+
+   If **either** signal shows an unresolved blocker you raised, this inbound is a **re-review** — go to the **PR review flow** regardless of how it is phrased. An author commenting "fixed both issues" / "addressed your feedback" / "pushed a fix" is a re-review trigger, **not** a thread-resolve trigger. A re-review is closed by re-deciding the verdict and landing a **formal** review via `POST /pulls/<N>/reviews`: `APPROVE` clears a sticky `CHANGES_REQUESTED`; a comment or a flat reply clears neither a formal block nor a flat-comment blocker — it just strands the verdict again, which is the original bug.
+
+2. **Am I being asked to review (first-time)?** Explicit `review_requested` inbound, or a human asking in plain language ("review this", "take a look at #N"). → **PR review flow** (see "When you are being asked to review").
+
+3. **Is this a reply inside an inline review thread I authored** (`pr:N` with `thread` set, on a thread whose root comment is mine)? → verify the fix at head SHA and **resolve the thread** (see "Resolving review threads you authored"). `resolve_review_thread` only works when `thread` is set on the origin; if there is **no** `thread`, this branch does not apply — do not attempt it, fall through to the table below.
+
+4. **None of the above** → use the routing table below.
+
+> The decisive question is **#1**. A blocking verdict you owe a PR is never discharged by a `channel_reply` or an `issue_comment` — neither carries review state, and neither clears a sticky `CHANGES_REQUESTED`. This applies to an **unresolved blocking obligation** (a live `CHANGES_REQUESTED`, or an unretracted blocker you raised in a flat comment), not to a stale `APPROVED` or a past non-blocking comment — those impose no closeout duty. When you do owe a block, the close-out is always a formal review via `POST /pulls/<N>/reviews`.
+
 ## What to do, by inbound type
 
-Every GitHub inbound lands on a `chat` keyed by its subject: `issue:N`, `pr:N`, or `discussion:N`. Pick your action from the kind of thing that arrived. The default action for anything addressed to you is a normal `channel_reply` in that thread; the **PR review flow** below is the one exception that requires delegation.
+Every GitHub inbound lands on a `chat` keyed by its subject: `issue:N`, `pr:N`, or `discussion:N`. **Run the triage above first.** Only if no triage branch matched do you pick an action from this table. The default action for anything addressed to you is a normal `channel_reply` in that thread; the **PR review flow** is the exception that requires delegation.
 
 | Inbound                                                  | Looks like                                                                           | What to do                                                                                                                                        |
 | -------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -43,31 +61,44 @@ A `review_request_removed` inbound ("removed your review request on PR #N") is t
 
 The `reviewer` subagent is the analyst; you are the integration layer between its output and GitHub's review API. It loads the `code-review` skill on demand and returns line-anchored findings inside a `<review>` block. Your job is mechanics: spawn, wait, translate, post.
 
+**The reviewer's `<review>` block is the only source of the verdict and the findings.** You do not review the PR yourself. Between spawning the reviewer and reading its result you do **no analysis of this PR** — do not run `gh pr diff`, do not read the changed files to form an opinion, do not draft a verdict. The reviewer runs on the `deep` model precisely so this judgment is not yours to make on the parent model. If you analyze the diff and post your own assessment while the reviewer is still running, you will post one verdict now and the reviewer's (often different) verdict when it completes — **two contradictory reviews on the same PR**, the exact failure this flow exists to prevent. Wait for the reviewer; post what it returns; nothing before that.
+
+**HARD RULE — a review with actionable findings is a formal review, never a flat comment.** If the reviewer returns **one or more** actionable findings (`blocker`/`concern`/`nit`), the ONLY acceptable way to deliver them is a formal review via `POST /pulls/<N>/reviews` (step 4) — `REQUEST_CHANGES`, `COMMENT`, or `APPROVE` per the verdict, with the line-anchored findings in `comments[]`. You may **never** flatten those findings into a `channel_reply` or a top-level issue comment, **even when** the `gh api` call fails. A 422 means an anchor is wrong (almost always a `line` not in the diff): re-anchor it or move that one finding into the top-level review `body`, then resubmit the formal review — do **not** abandon the formal review and post prose instead. A flat "## Review … two blockers" comment is a bug, not a fallback: it strands the findings without line anchors and is the exact failure this rule exists to prevent. The flat/issue-comment path is reserved for the **zero-actionable-findings** branch only (see below). If you genuinely cannot land a formal review after fixing anchors, say so plainly and post nothing that claims a review happened — silence beats a false receipt.
+
 1. **Confirm the target, and check whether you already reviewed it.** Capture the PR number, the repo, and the head SHA — you may need the SHA to read files at the revision the reviewer analyzed.
 
    ```sh
    gh pr view <N> --repo owner/repo --json title,body,baseRefName,headRefOid,files
    ```
 
-   Then check for a **prior review by you** — this is what makes the current request a _re-review_ (the author pushed fixes and re-requested you after you previously blocked the PR):
+   Then check for an **unresolved blocking obligation of yours** — this is what makes the current request a _re-review_ (the author pushed fixes after you previously blocked the PR). As in triage #1, a block can live in **two** places, and you must check both:
 
    ```sh
+   # (a) formal review state
    gh api --paginate --slurp /repos/owner/repo/pulls/<N>/reviews --jq 'add | [.[] | select(.user.login == "<your-login>" and (.state == "CHANGES_REQUESTED" or .state == "APPROVED"))] | last | .state'
+   # (b) flat-comment blocker you authored (when (a) is empty)
+   gh api --paginate /repos/owner/repo/issues/<N>/comments --jq '[.[] | select(.user.login == "<your-login>")]'
    ```
 
-   If that prints `CHANGES_REQUESTED`, treat the current request as a **re-review** and carry that fact into the spawn in step 2; any other output (including empty) means no live block, so handle the request normally. (`<your-login>` is your GitHub App login, typically `name[bot]`.)
+   If (a) prints `CHANGES_REQUESTED`, **or** (a) is empty but (b) surfaces a comment of yours that requested changes / raised blockers and has not since been superseded by a formal review or a clear retraction, treat the current request as a **re-review** and carry that fact — including which form the prior block took — into the spawn in step 2. Only when **neither** signal shows an unresolved block do you handle the request normally. (`<your-login>` is your GitHub App login, typically `name[bot]`.)
 
-   Two things make this query load-bearing — both are bugs if you simplify it:
+   Two things make the formal-review query load-bearing — both are bugs if you simplify it:
    - **Filter to _decision_ states, not the latest review row.** GitHub's sticky block is cleared only by a later `APPROVED` (or a dismissal) from the same reviewer — a later `COMMENTED` review does **not** clear it. So a history of `CHANGES_REQUESTED` → `COMMENTED` is _still blocked_, even though the latest row is `COMMENTED`. Selecting `last` over the raw review list would misread that as "not a re-review". Filtering to `{CHANGES_REQUESTED, APPROVED}` first, then taking `last`, asks the right question: "what is my latest _blocking decision_, ignoring non-deciding comments?" (Dismissed reviews surface as `state: "DISMISSED"`, so they're correctly excluded from the decision set too.)
    - **`--paginate --slurp` is mandatory.** GitHub returns reviews 30 per page; a bot on a long-lived PR can have its blocking `CHANGES_REQUESTED` past the first page. Without paginating, that review is invisible and a genuine re-review silently falls back to the plain-comment path. `--slurp` collects every page into one array of arrays; the `add` concatenates them before filtering.
 
 2. **Spawn the `reviewer` subagent with the PR target.** Use `run_in_background: true` so you stay responsive while the deep model works. Pass the PR URL (or `owner/repo#N`) plus any context the requester gave you (focus areas, specific files, etc.). The reviewer fetches the diff itself (`gh pr diff`, `gh api /repos/.../pulls/<n>`), loads the `code-review` skill, and returns a `<review>` block whose code findings carry `location="path:line"`.
 
-   **If step 1 found a prior `CHANGES_REQUESTED` review, say so in the spawn payload** — e.g. _"This is a re-review: you previously requested changes on this PR (the prior blockers were …). Verify they are resolved and return `approve` or `request-changes` — a re-review must re-decide the blocking state, not return `comment`."_ The reviewer's `code-review` skill enforces the same rule, but telling it the prior verdict is what lets it apply that rule; a fresh reviewer session has no memory of your earlier review.
+   **If step 1 found an unresolved blocking obligation — a formal `CHANGES_REQUESTED` _or_ an unretracted flat-comment blocker — say so in the spawn payload** — e.g. _"This is a re-review: you previously blocked this PR (the prior blockers were …; the block was a formal `CHANGES_REQUESTED` / a flat PR comment). Verify they are resolved and return `approve` or `request-changes` — a re-review must re-decide the blocking state, not return `comment`."_ The reviewer's `code-review` skill enforces the same rule, but telling it the prior blockers (and which form they took) is what lets it apply that rule; a fresh reviewer session has no memory of your earlier block. The flat-comment case especially must be passed through — the reviewer cannot recover it from review state, so omitting it would silently drop the re-review context the moment the flow starts.
+
+   Do **not** post an "on it" acknowledgement comment before spawning the reviewer — the runtime already adds an :eyes: reaction to the PR the moment it engages, so a "looking into this" comment is redundant noise. Just spawn the reviewer with `run_in_background: true`; the formal review is your reply. If you want to acknowledge explicitly, use `channel_react({ emoji: "eyes" })`, which reacts without posting a comment.
+
+   After spawning, **end your turn** — the background reviewer wakes you with a completion `<system-reminder>` (step 3). "Stay responsive" means you remain free to handle _other_ chats meanwhile; it does **not** license you to keep working _this_ PR. Do not poll `subagent_output` in a busy-wait, and do not fill the wait by reviewing the diff yourself (see the exclusivity rule at the top of this flow). The next thing you do on this PR is read the reviewer's `<review>` block when the reminder arrives.
 
-   Do **not** post an "on it" acknowledgement comment before spawning the reviewer — the runtime already adds an :eyes: reaction to the PR the moment it engages, so a "looking into this" comment is redundant noise. Just spawn the reviewer with `run_in_background: true` and keep working; the formal review is your reply. If you want to acknowledge explicitly, use `channel_react({ emoji: "eyes" })`, which reacts without posting a comment.
+3. **On the completion `<system-reminder>`, first check you have not already posted — then** call `subagent_output({ task_id })` to read the reviewer's final assistant message.
 
-3. **Wait for the completion `<system-reminder>`,** then call `subagent_output({ task_id })` to read the reviewer's final assistant message. The structured payload looks like:
+   **One verdict per PR per request — guard this before you read or post anything.** The completion reminder is not a license to post; it is a wake-up. The very first thing you do on this turn is ask: have I **already posted a review or verdict on this PR during this engagement**? If yes, stop here — do not fetch the reviewer output, do not translate, do not post. Call `skip_response({ reason: "review already posted for this PR" })` and end the turn. Posting the reminder's result on top of a verdict you already shipped is how a PR ends up with two reviews — and if the two disagree (because the earlier one was your own premature take), it contradicts you in public. Only when no review has gone out yet do you proceed to read and post below — which is the normal path, since you waited for the reviewer instead of reviewing it yourself.
+
+   With that confirmed, read the reviewer's final assistant message. The structured payload looks like:
 
    ```xml
    <review>
@@ -97,10 +128,14 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
 
    **Operator approval policy.** If the inbound carries a note that PR approval is disabled (`channels.github.review.approve: false` — the adapter appends "Operator policy: PR approval is disabled for this agent" to the message), you must **not** submit an `APPROVE`. Map an `approve` verdict to `COMMENT` instead: post the same `<summary>` and all inline `comments[]` as a `COMMENT` review, just without the formal approval. `request-changes` and `comment` verdicts are unaffected (they never approve). Absent that note, approval is enabled and the table above applies unchanged.
 
-   **Re-review.** If step 1 established this is a re-review (your latest blocking decision was `CHANGES_REQUESTED`), the result MUST clear or re-assert that block — never a top-level PR comment. On GitHub, `CHANGES_REQUESTED` is sticky: **only** a fresh `APPROVE` from you, or a dismissal of your prior review, clears it. A plain issue comment does **not** clear it, and — critically — **neither does a `COMMENT` review.** So even if the reviewer returns zero actionable findings, do **not** take the `comment` → top-level-comment branch below for a re-review. The reviewer's skill is instructed not to return `comment` on a re-review; if it does anyway despite a reachable diff, prefer `approve` when the prior blockers are visibly resolved in the diff, otherwise `request-changes` — and say which in your reasoning. Resolve the re-review by verdict:
+   **Re-review.** If step 1 established this is a re-review (an unresolved blocking obligation of yours — a formal `CHANGES_REQUESTED` **or** an unretracted flat-comment blocker), the result MUST clear or re-assert that block — never a top-level PR comment. The clearing mechanics depend on which form the prior block took:
+   - **Prior block was a formal `CHANGES_REQUESTED`.** It is sticky: **only** a fresh `APPROVE` from you, or a dismissal of your prior review, clears it. A plain issue comment does **not** clear it, and — critically — **neither does a `COMMENT` review.**
+   - **Prior block was a flat comment** (no formal `CHANGES_REQUESTED` exists). There is no sticky GitHub state to clear, but the obligation is still yours to discharge as a **formal** review so the verdict finally lands as review state: submit `APPROVE` (resolved, approval enabled) or `REQUEST_CHANGES` (not resolved). Do not discharge a flat-comment block with another flat comment — that re-strands the verdict, the original bug.
+
+   So even if the reviewer returns zero actionable findings, do **not** take the `comment` → top-level-comment branch below for a re-review. The reviewer's skill is instructed not to return `comment` on a re-review; if it does anyway despite a reachable diff, prefer `approve` when the prior blockers are visibly resolved in the diff, otherwise `request-changes` — and say which in your reasoning. Resolve the re-review by verdict:
    - **`request-changes`** — submit a fresh `REQUEST_CHANGES` review (re-asserts the block with the new findings). Straightforward.
    - **`approve`, approval enabled** — submit `APPROVE`. This clears the block.
-   - **`approve`, approval disabled (`channels.github.review.approve: false`)** — you cannot `APPROVE`, and a `COMMENT` review will **not** clear the sticky block, so the PR would stay blocked by your stale review. Clear it explicitly by **dismissing your own prior `CHANGES_REQUESTED` review**. Grab that review's `id` by re-running the step-1 query with the trailing filter changed from `| .state` to `| {state, id}` (same `select`), take the entry whose `state` is `CHANGES_REQUESTED`, then:
+   - **`approve`, approval disabled (`channels.github.review.approve: false`)** — you cannot `APPROVE`. How you close out depends on the prior block's form. **If the prior block was a flat comment** (no formal `CHANGES_REQUESTED`), there is no sticky state to clear: submit a `COMMENT` review carrying the `<summary>` so the verdict lands as review state, and you are done — nothing to dismiss. **If the prior block was a formal `CHANGES_REQUESTED`**, a `COMMENT` review will **not** clear the sticky block, so the PR would stay blocked by your stale review; clear it explicitly by **dismissing your own prior `CHANGES_REQUESTED` review**. Grab that review's `id` by re-running the step-1 formal-review query with the trailing filter changed from `| .state` to `| {state, id}` (same `select`), take the entry whose `state` is `CHANGES_REQUESTED`, then:
 
      ```sh
      gh api -X PUT /repos/owner/repo/pulls/<N>/reviews/<review_id>/dismissals -f message="Blockers resolved; dismissing my prior changes request per operator approval-disabled policy." -f event=DISMISS
@@ -110,7 +145,7 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
 
    Then submit the review. **Write the JSON payload to a file with the `write` tool, then run a single bare `gh api --input <file>`** — two steps:
 
-   First write `/tmp/review.json` (via the `write` tool, not bash):
+   First write `/tmp/review-<N>.json` (via the `write` tool, not bash) — `/tmp` is per-session scratch, and the `<N>` keeps concurrent reviews in one session from colliding:
 
    ```json
    {
@@ -131,7 +166,7 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
    Then post it:
 
    ```sh
-   gh api -X POST /repos/owner/repo/pulls/<N>/reviews --input /tmp/review.json
+   gh api -X POST /repos/owner/repo/pulls/<N>/reviews --input /tmp/review-<N>.json
    ```
 
    **A repo-targeting `gh` command must be a single bare `gh` invocation — no pipes, `;`, `&&`, heredocs, or command substitution.** The `github-cli-auth` plugin injects the GitHub App token into the command's environment, so any sibling/upstream stage in a pipeline would inherit a live token; the runtime blocks those shapes. That is why the old `cat <<'JSON' | gh api --input -` heredoc-pipe no longer works: write the JSON to a file and feed it with `--input <file>` instead. Do **not** use `-f body=...` or `-F 'comments[][body]=...'`: those go through shell argument parsing, so backticks trigger command substitution. The file passes the JSON through untouched — backticks, newlines, and `${...}` all survive verbatim. The same file-then-`--input` pattern applies to any `gh api` POST whose body contains backticks, embedded newlines, or shell metacharacters.
@@ -155,7 +190,7 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
 A finding is "actionable" if its severity is `blocker`, `concern`, or `nit`. The inline-review post in step 4 applies whenever the actionable count is **at least one**. When the reviewer returns **exactly zero** actionable findings (only `praise`, or none), there is nothing to anchor inline — handle by verdict:
 
 - `approve` → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array). **If the operator approval policy above disabled approval, submit a `COMMENT` review instead — same `<summary>` as the review body, `event: "COMMENT"`, no `comments[]` array. Keep it a formal review, not a top-level issue comment, so the review metadata and flow are preserved.** (Re-review caveat: a `COMMENT` review does **not** clear a sticky `CHANGES_REQUESTED` block. If this is a re-review under approval-disabled policy, follow the step-4 re-review branch — dismiss your prior review — instead of relying on this `COMMENT`.)
-- `comment` → post the summary as a top-level PR comment via `gh api -X POST /repos/.../issues/<N>/comments` instead of submitting an empty review. **Exception — re-reviews:** if this is a re-review (your latest blocking decision was `CHANGES_REQUESTED`), a top-level comment does not clear the sticky block. Do not use this branch; resolve it via the step-4 re-review branch (`APPROVE` if resolved and approval is enabled, the dismissal endpoint if resolved but approval is disabled, `REQUEST_CHANGES` if not resolved).
+- `comment` → post the summary as a top-level PR comment via `gh api -X POST /repos/.../issues/<N>/comments` instead of submitting an empty review. **Exception — re-reviews:** if this is a re-review (you have an unresolved blocking obligation — a formal `CHANGES_REQUESTED` **or** an unretracted flat-comment blocker), a top-level comment discharges neither. Do not use this branch; resolve it via the step-4 re-review branch (`APPROVE` if resolved and approval is enabled, the dismissal endpoint if a formal block is resolved but approval is disabled, `REQUEST_CHANGES` if not resolved).
 - `request-changes` → submit `REQUEST_CHANGES` with the `<summary>` as the review body and no `comments[]` array. This combination is rare (the reviewer's contract says `request-changes` requires at least one blocker or load-bearing concern); if it happens, faithfully encode the verdict and trust the reviewer's reasoning is in the summary.
 
 The bundled `agent-browser` is **not** for PR reviews — `gh api` is faster and more reliable. Only use the browser when the API genuinely can't reach what you need.
@@ -174,11 +209,30 @@ Do not resolve on a bare "done" claim. A reply that says "fixed" is a prompt to
 2. Read the lines your comment anchored to, at that SHA: `gh api /repos/owner/repo/contents/<path>?ref=<headRefOid>` (or `gh pr diff <N>` to see what the new push changed). Confirm the change actually addresses the concern your comment raised — not a different line, not a partial fix.
 3. Only when the code at head genuinely resolves the finding do you resolve the thread. If the fix is partial or misses the point, **reply in the thread** explaining what's still open and leave it unresolved.
 
-If the author merely **replied** without pushing (e.g. "this is intentional because …") and their reasoning settles it, that is also "addressed" — **resolve first, then optionally leave a one-line acknowledgement.** Order matters: a bare `channel_reply` ends your turn (see "Mid-turn status replies need `continue: true`" above), so acknowledging _before_ you resolve would stop the turn and the `resolveReviewThread` mutation would never run, leaving the thread open. Resolve, then reply. If you genuinely want to acknowledge before resolving, the acknowledgement must use `channel_reply({ …, continue: true })` so the turn survives long enough to resolve. If their reasoning does **not** settle it, keep the thread open and answer.
+If the author merely **replied** without pushing (e.g. "this is intentional because …") and their reasoning settles it, that is also "addressed". If their reasoning does **not** settle it, keep the thread open and answer instead.
+
+> **The verify and the resolve are one action, not two.** Once you've verified the fix, your acknowledgement reply **is** the close-out — carry `resolve_review_thread: true` on it. The common failure is posting a bare "Verified at \<sha\> — thanks, that addresses it" with the flag omitted: that reads as closed but leaves the thread **open**, because a successful reply ends your turn and the resolve can't happen in a later one. The flag is technically optional (nothing rejects a reply without it), but on an acknowledgement it is the only thing that actually closes the thread — so treat it as part of the acknowledgement, not an afterthought.
+
+### How to resolve — `channel_reply({ resolve_review_thread: true })`
+
+Once you have verified the fix, **acknowledge and resolve in one call**: pass `resolve_review_thread: true` to your `channel_reply`. The runtime resolves the thread you're replying in **before** it posts your acknowledgement, then posts the reply:
+
+```
+channel_reply({ text: "Verified — the fix addresses the concern. Thanks!", resolve_review_thread: true })
+```
+
+This is the correct path and it removes a footgun. A bare `channel_reply` ends your turn the moment it lands, so a resolve attempted _after_ the acknowledgement would never run — the thread would stay open even though you "handled" it. The flag resolves first, so a normal final reply still closes the thread. You do **not** need `continue: true` for this: resolution happens inside the same call, before the turn ends.
+
+Two guarantees make the flag safe to use as your default:
+
+- **Author check is enforced in code.** The runtime only resolves a thread whose root comment **you** authored; a request to resolve a human reviewer's thread is refused, and the reply is **not** posted. You cannot accidentally close someone else's open question.
+- **A failed resolve blocks the reply.** If the resolve fails (permission denied, wrong author, the fix doesn't verify on the API side), `channel_reply` is denied and posts nothing — so you never end up with a cheerful "looks resolved" comment sitting next to a still-open thread. Read the denial, fix the cause, and retry.
+
+The flag is valid only on a github session replying inside a thread (`thread` set on the origin). It is ignored — and denied — elsewhere. If the thread is already resolved or already gone, the reply still posts (nothing left to close).
 
-### How to resolve — `resolveReviewThread` GraphQL mutation
+### Fallback — the raw `resolveReviewThread` GraphQL mutation
 
-There is no REST endpoint for this. Resolution is a GraphQL mutation that takes the thread's **node id** (`PRRT_…`), not the comment's numeric id. Two steps: find the thread id, then resolve it.
+Prefer the flag above. Reach for the raw mutation only when you need to resolve a thread you are **not** currently replying in, or to debug. There is no REST endpoint for this. Resolution is a GraphQL mutation that takes the thread's **node id** (`PRRT_…`), not the comment's numeric id. Two steps: find the thread id, then resolve it.
 
 1. **Find the node id of the thread you authored.** Query the PR's review threads and pick the one whose root comment is yours and matches the `thread` you're replying in:
 

package/src/skills/typeclaw-memory/SKILL.md

@@ -25,12 +25,14 @@ Citations in shard bodies use the canonical form `streams/yyyy-MM-dd#<fragment-i
 
 When index-mode injection hides bodies, or when you need recent fragments the dreaming subagent hasn't consolidated yet, use `memory_search({query, asRegex?, full?, maxResults?})`. It searches BOTH topic shards under `memory/topics/` and undreamed stream events under `memory/streams/`. Substring (case-insensitive) by default; `asRegex: true` for regex.
 
+Plain queries are **phrase-first with a word fallback**: the whole query is tried as one substring, and only if that finds nothing is the query split on whitespace and the distinct words OR-matched (ranked by how many words each hit contains). So a descriptive multi-word query like `quarterly regional revenue summary` still returns results even when no entry contains that exact phrase. You don't need to pre-split queries into single keywords — but a focused phrase still wins when an entry contains it verbatim. Regex queries never fall back (whitespace stays part of the pattern).
+
 Results are discriminated by `source`:
 
 - `source: "topic"` — fields `shardPath`, `slug`, `heading`, `excerpt`, `fullBody?`
 - `source: "stream"` — fields `streamPath`, `date`, `eventId?` (citation-format `streams/yyyy-MM-dd#<id>` for fragments; absent for legacy prose), `topic`, `excerpt`, `fullBody?`
 
-Topic matches come first (alphabetical by slug); then stream matches (newest day first). `full: true` returns the entire shard or fragment body. `maxResults` truncates streams before topics when exhausted.
+Ordering depends on mode. Exact-phrase (and regex) results list all topic matches first (alphabetical by slug), then stream matches (newest day first), and `maxResults` truncates streams before topics. Word-fallback results are instead ranked by matched-word count — that same topic-first/stream-newest order is only the tiebreak within a score band, so a higher-scoring stream can precede a lower-scoring topic, and `maxResults` drops the lowest-scored tail regardless of source. `full: true` returns the entire shard or fragment body.
 
 ## Per-shard truncation
 

package/src/tui/format.ts

@@ -63,10 +63,10 @@ function humanizeArgs(name: string, args: unknown): string | null {
       return humanizeFindArgs(args)
     case 'ls':
       return humanizeLsArgs(args)
-    case 'websearch':
-      return humanizeWebsearchArgs(args)
-    case 'webfetch':
-      return humanizeWebfetchArgs(args)
+    case 'web_search':
+      return humanizeWebSearchArgs(args)
+    case 'web_fetch':
+      return humanizeWebFetchArgs(args)
     default:
       return null
   }
@@ -123,14 +123,14 @@ function humanizeLsArgs(args: ArgRecord): string | null {
   return asString(args.path) ?? '.'
 }
 
-function humanizeWebsearchArgs(args: ArgRecord): string | null {
+function humanizeWebSearchArgs(args: ArgRecord): string | null {
   const query = asString(args.query)
   if (query === null) return null
   const source = asString(args.source)
   return source && source !== 'web' ? `"${query}" (${source})` : `"${query}"`
 }
 
-function humanizeWebfetchArgs(args: ArgRecord): string | null {
+function humanizeWebFetchArgs(args: ArgRecord): string | null {
   return asString(args.url)
 }
 
@@ -153,8 +153,8 @@ function enrichResult(name: string, result: ArgRecord): string | null {
       return enrichBashResult(result)
     case 'read':
       return enrichReadResult(result)
-    case 'websearch':
-      return enrichWebsearchResult(result)
+    case 'web_search':
+      return enrichWebSearchResult(result)
     default:
       return null
   }
@@ -187,7 +187,7 @@ function enrichReadResult(result: ArgRecord): string | null {
   return mime ? `[image: ${mime}]` : '[image]'
 }
 
-function enrichWebsearchResult(result: ArgRecord): string | null {
+function enrichWebSearchResult(result: ArgRecord): string | null {
   const details = isObject(result.details) ? result.details : null
   if (details === null) return null
   const results = Array.isArray(details.results) ? details.results : null
@@ -198,13 +198,13 @@ function enrichWebsearchResult(result: ArgRecord): string | null {
   const source = asString(details.source) ?? ''
   const header = query ? `${results.length} result${results.length === 1 ? '' : 's'} for "${query}" (${source})` : null
   const lines = results
-    .map((entry, i) => formatWebsearchEntry(entry, i + 1))
+    .map((entry, i) => formatWebSearchEntry(entry, i + 1))
     .filter((line): line is string => line !== null)
   if (lines.length === 0) return extractContentText(result)
   return header === null ? lines.join('\n') : `${header}\n${lines.join('\n')}`
 }
 
-function formatWebsearchEntry(entry: unknown, index: number): string | null {
+function formatWebSearchEntry(entry: unknown, index: number): string | null {
   if (!isObject(entry)) return null
   const title = asString(entry.title)
   const url = asString(entry.url)

package/typeclaw.schema.json

@@ -548,10 +548,20 @@
             },
             "review": {
               "default": {
+                "on": "review_requested",
                 "approve": true
               },
               "type": "object",
               "properties": {
+                "on": {
+                  "default": "review_requested",
+                  "type": "string",
+                  "enum": [
+                    "review_requested",
+                    "opened",
+                    "off"
+                  ]
+                },
                 "approve": {
                   "default": true,
                   "type": "boolean"