typeclaw 0.24.0 → 0.25.0

package/src/sandbox/session-tmp.ts

@@ -0,0 +1,43 @@
+import { mkdir } from 'node:fs/promises'
+import { isAbsolute, join, relative, resolve } from 'node:path'
+
+// Per-session scratch lives on the REAL container /tmp, namespaced by session id.
+// It sits OUTSIDE the agent folder on purpose: the agent folder's `sessions/` is
+// force-committed by typeclaw, and scratch must never be committed. The real
+// /tmp is ephemeral (dies with the container) and already the natural home for
+// throwaway files, so a per-session subdir of it gives `/tmp` semantics without
+// either sharing the whole container /tmp into a sandboxed role or persisting
+// anything into the project surface.
+export const SESSION_TMP_ROOT = '/tmp/typeclaw-session'
+
+export function sessionTmpDir(sessionId: string): string {
+  return join(SESSION_TMP_ROOT, sessionId)
+}
+
+export async function ensureSessionTmpDir(sessionId: string): Promise<string> {
+  const dir = sessionTmpDir(sessionId)
+  await mkdir(dir, { recursive: true, mode: 0o700 })
+  return dir
+}
+
+export function isUnderTmp(agentDir: string, rawPath: string): boolean {
+  const resolved = resolve(agentDir, rawPath)
+  return resolved === '/tmp' || isInside('/tmp', resolved)
+}
+
+// Maps a model-facing /tmp path to its per-session backing path. Returns
+// undefined when the path is not under /tmp (caller leaves it untouched). The
+// model keeps writing/reading `/tmp/foo`; only the on-disk target moves to
+// `<SESSION_TMP_ROOT>/<sid>/foo`, which is the same dir bwrap binds over `/tmp`
+// for the sandboxed bash that reads it back.
+export function mapVirtualTmpPath(agentDir: string, sessionId: string, rawPath: string): string | undefined {
+  const resolved = resolve(agentDir, rawPath)
+  if (resolved !== '/tmp' && !isInside('/tmp', resolved)) return undefined
+  const rel = relative('/tmp', resolved)
+  return rel === '' ? sessionTmpDir(sessionId) : join(sessionTmpDir(sessionId), rel)
+}
+
+function isInside(parent: string, child: string): boolean {
+  const rel = relative(parent, child)
+  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)
+}

package/src/sandbox/writable-zones.ts

@@ -1,11 +1,16 @@
-import { lstat } from 'node:fs/promises'
-import path, { join } from 'node:path'
+import { lstat, mkdir, readFile, writeFile } from 'node:fs/promises'
+import path, { isAbsolute, join, resolve } from 'node:path'
 
 export type WritableZones = {
   dirs: string[]
   files: string[]
 }
 
+export type ProtectedZones = {
+  dirs: string[]
+  files: string[]
+}
+
 // SECURITY: a blanket RW bind is coarser than the write/edit guards, so this set
 // is deliberately NARROWER than the write/edit allowlist — only genuinely
 // free-write scratch zones. `.agents/skills` and `packages` are excluded: the
@@ -13,7 +18,25 @@ export type WritableZones = {
 // guard and the latter holds executable plugin code; bash must not get blanket
 // RW to either. Skill authoring and package writes go through the guarded
 // write/edit tool only.
-const WRITABLE_DIRS = ['workspace', 'public', 'mounts'] as const
+// `.git` is writable so a member can `git add`/`git commit` their own edits.
+// This is the AGENT'S OWN repo, not a shared/upstream one, so writing history
+// is not a privilege boundary: a low-trust role staging a tracked path it
+// cannot edit in the worktree (e.g. via `git update-index --cacheinfo` plumbing)
+// only writes the agent's own history — content the backup runner already
+// force-commits on idle regardless. So we deliberately do NOT try to confine
+// commit *content* to the worktree write-allowlist; that boundary governs the
+// working tree, not the object database.
+//
+// The one thing writable `.git` must NOT grant is code execution in the
+// UNSANDBOXED runtime (backup/dreaming commit the same .git out of band): a
+// planted `.git/hooks/*` or a `core.hooksPath` in `.git/config` would fire there
+// as a higher-privilege process. resolveProtectedZones re-binds `.git/hooks` and
+// `.git/config` read-only (after the writable .git bind, last-op-wins) to close
+// exactly that escalation.
+const WRITABLE_DIRS = ['workspace', 'public', 'mounts', '.git'] as const
+
+const PROTECTED_GIT_DIRS = ['.git/hooks'] as const
+const PROTECTED_GIT_FILES = ['.git/config'] as const
 
 // Bash may EDIT these when present; creating a MISSING root file goes through
 // write/edit (bwrap cannot RW-bind a non-existent source without pre-creating it).
@@ -43,6 +66,83 @@ export async function resolveWritableZones(agentDir: string): Promise<WritableZo
   return { dirs, files }
 }
 
+// Read-only re-protections rendered on top of the writable .git bind. Unlike
+// the writable resolvers, this MUST NOT drop absent entries: .git is writable,
+// so a path absent at jail-build time would otherwise be CREATED by sandboxed
+// bash (e.g. a planted .git/hooks/pre-commit) and then executed by the
+// unsandboxed runtime git ops. So we ensure each protected path exists first,
+// then always RO-bind it — a read-only bind of a real dir blocks creating
+// children inside it (EROFS), and a read-only bind of config keeps its real
+// content readable (commits need user.name/email) while blocking mutation.
+//
+// We also resolve the effective core.hooksPath from the real (about-to-be-RO)
+// config: if it already points at a writable location (e.g. workspace/hooks),
+// the .git/hooks RO-bind alone would not cover it, so that dir is protected too.
+export async function resolveProtectedZones(agentDir: string): Promise<ProtectedZones> {
+  const dirs: string[] = []
+  for (const rel of PROTECTED_GIT_DIRS) {
+    dirs.push(await ensureProtectedDir(join(agentDir, rel)))
+  }
+  const files: string[] = []
+  for (const rel of PROTECTED_GIT_FILES) {
+    files.push(await ensureProtectedFile(join(agentDir, rel)))
+  }
+
+  const hooksPathDir = await resolveEffectiveHooksPath(agentDir)
+  if (hooksPathDir !== undefined && !dirs.includes(hooksPathDir)) {
+    dirs.push(await ensureProtectedDir(hooksPathDir))
+  }
+
+  return { dirs, files }
+}
+
+// Fail closed: a symlink at a protected path would make the RO bind follow it
+// elsewhere, so reject it rather than silently protect the wrong target.
+async function ensureProtectedDir(target: string): Promise<string> {
+  await mkdir(target, { recursive: true })
+  await assertNotSymlink(target)
+  return target
+}
+
+async function ensureProtectedFile(target: string): Promise<string> {
+  if (!(await isRealEntry(target, 'file'))) {
+    try {
+      await writeFile(target, '', { flag: 'wx' })
+    } catch {
+      // Lost a race (or it appeared); the symlink check below still guards it.
+    }
+  }
+  await assertNotSymlink(target)
+  return target
+}
+
+async function assertNotSymlink(target: string): Promise<void> {
+  const stats = await lstat(target)
+  if (stats.isSymbolicLink()) {
+    throw new Error(`sandbox: refusing to protect symlinked path ${target}`)
+  }
+}
+
+// Reads core.hooksPath straight from .git/config text (the file is about to be
+// RO-bound, so its content is the trusted baseline). Returns the resolved
+// absolute dir only when it lands inside agentDir — an outside path is not
+// writable by the jail and a relative path resolves against the repo root, per
+// gitconfig semantics.
+async function resolveEffectiveHooksPath(agentDir: string): Promise<string | undefined> {
+  let text: string
+  try {
+    text = await readFile(join(agentDir, '.git', 'config'), 'utf8')
+  } catch {
+    return undefined
+  }
+  const match = text.match(/^\s*hooksPath\s*=\s*(.+?)\s*$/m)
+  if (match === null) return undefined
+  const raw = match[1]?.trim()
+  if (raw === undefined || raw.length === 0) return undefined
+  const resolved = isAbsolute(raw) ? resolve(raw) : resolve(agentDir, raw)
+  return isInside(agentDir, resolved) ? resolved : undefined
+}
+
 // SECURITY: a writable RW bind renders AFTER the masks and last-op-wins, so an
 // RW bind on a masked path would re-expose the real (hidden) directory. Drop any
 // writable zone that is, or is nested under, a masked path so the confidentiality

package/src/server/command-runner.ts

@@ -389,7 +389,7 @@ export async function runPromptForCommand(args: {
   // Mirrors src/agent/multimodal/look-at.ts: spawn a session, prompt, capture
   // the final assistant text, dispose. Unlike look-at we want the FULL agent
   // toolset (no `tools: []` / `customTools: []` overrides) so the model can
-  // call channel_send, websearch, etc. The system prompt is composed from
+  // call channel_send, web_search, etc. The system prompt is composed from
   // the agent folder's IDENTITY/SOUL/MEMORY files via the default resource
   // loader (no `systemPromptOverride`).
   const snapshot = args.runtime.get()

package/src/server/index.ts

@@ -11,6 +11,7 @@ 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'
@@ -25,6 +26,7 @@ import {
   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'
@@ -931,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)

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

@@ -14,9 +14,27 @@ GitHub renders normal Markdown in issues, PRs, discussions, and review comments.
 
 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                                                                                                                                        |
 | -------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -53,21 +71,24 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
    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.
 
@@ -107,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
@@ -120,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
    {
@@ -141,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.
@@ -165,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.
@@ -186,6 +211,8 @@ Do not resolve on a bare "done" claim. A reply that says "fixed" is a prompt to
 
 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:

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)