typeclaw 0.21.0 → 0.22.0

package/src/bundled-plugins/bun-hygiene/policy.ts

@@ -0,0 +1,318 @@
+import { ACKNOWLEDGE_GUARDS, type GuardBlock, isGuardAcknowledged } from '../guard/policy'
+
+export const GUARD_GLOBAL_INSTALL = 'globalInstall'
+export const GUARD_NON_BUN_PACKAGE_MANAGER = 'nonBunPackageManager'
+
+const NON_BUN_MANAGERS = new Set(['npm', 'npx', 'pnpm', 'pnpx', 'yarn'])
+const INSTALL_SUBCOMMANDS = new Set(['install', 'i', 'add'])
+
+export function checkBunHygieneGuard(options: { tool: string; args: Record<string, unknown> }): GuardBlock | undefined {
+  const { tool, args } = options
+  if (tool !== 'bash') return undefined
+
+  const command = args.command
+  if (typeof command !== 'string') return undefined
+
+  const verdict = classify(command)
+  if (verdict === undefined) return undefined
+  if (verdict.kind === 'global-install') return blockGlobalInstall(verdict.label, args)
+  return blockNonBunManager(verdict.manager, args)
+}
+
+type Verdict = { kind: 'global-install'; label: string } | { kind: 'non-bun'; manager: string }
+
+// Why a segment model instead of one big regex: every gap in a raw-string match
+// is a shell-structure gap. Splitting into segments first means a global flag on
+// a *different* command (`npm install\n-g x` — two commands) can never combine
+// with an install on another, leading assignment words (`FOO=bar npm ...`) are
+// stripped uniformly, and `--global=false` is inspected as a real token. The
+// global-install verdict wins over the plain non-bun verdict (it's the more
+// specific violation, and acknowledging it is meant to let the whole thing run).
+function classify(command: string): Verdict | undefined {
+  let fallback: Verdict | undefined
+  for (const segment of splitSegments(command)) {
+    const words = segment.map(normalizeWord)
+    const manager = leadingCommandWord(words)
+    if (manager === undefined) continue
+
+    // `bun` is the allowed manager, but a `bun add -g` still installs to ~/.bun
+    // (outside /agent) and is wiped on restart, so it is a global install too —
+    // just never a plain non-bun violation.
+    const isBun = manager === 'bun'
+    if (!isBun && !NON_BUN_MANAGERS.has(manager)) continue
+
+    const label = globalInstallLabel(manager, words)
+    if (label !== undefined) return { kind: 'global-install', label }
+    if (!isBun) fallback ??= { kind: 'non-bun', manager }
+  }
+  return fallback
+}
+
+// Split on real command separators (`;`, `&&`, `||`, `|`, `&`, newline, `\r`)
+// and on subshell / command-substitution openers (`(`, `$(`, backtick), then
+// tokenize each segment into whitespace-separated words. Quote-aware so a
+// separator inside quotes stays literal; backslash escapes the next character
+// (so `\;` and `\ ` are literal, not separators/breaks). Word-level only — it
+// does not interpret redirections or expansions beyond boundary marking.
+function splitSegments(command: string): string[][] {
+  const segments: string[][] = []
+  let words: string[] = []
+  let current = ''
+  let hasWord = false
+  let quote: '"' | "'" | null = null
+  // Tracks a command substitution entered from inside a double quote, so the
+  // outer double-quote mode is restored when the substitution closes. Bash runs
+  // `$(...)` and backtick substitutions inside double quotes (but not single),
+  // so `echo "$(npm install)"` must be scanned for a manager.
+  let commandSub: { kind: '`' | '$('; depth: number; resumeQuote: '"' } | null = null
+
+  const flushWord = (): void => {
+    if (hasWord) {
+      words.push(current)
+      current = ''
+      hasWord = false
+    }
+  }
+  const flushSegment = (): void => {
+    flushWord()
+    if (words.length > 0) {
+      segments.push(words)
+      words = []
+    }
+  }
+
+  for (let i = 0; i < command.length; i++) {
+    const ch = command[i]
+    if (quote !== null) {
+      // A `$(` or backtick inside a double quote opens a command substitution
+      // that Bash executes; scan its body as a fresh segment, remembering to
+      // resume double-quote mode when it closes.
+      if (quote === '"' && ch === '`') {
+        flushSegment()
+        commandSub = { kind: '`', depth: 0, resumeQuote: '"' }
+        quote = null
+        continue
+      }
+      if (quote === '"' && ch === '$' && command[i + 1] === '(') {
+        flushSegment()
+        commandSub = { kind: '$(', depth: 1, resumeQuote: '"' }
+        quote = null
+        i++
+        continue
+      }
+      if (ch === quote) quote = null
+      else {
+        current += ch
+        hasWord = true
+      }
+      continue
+    }
+    // Close of a command substitution opened from inside a double quote:
+    // restore the outer double-quote mode so the rest of the string (and any
+    // trailing `&&`/`;`) is parsed correctly rather than re-quoted.
+    if (commandSub?.kind === '`' && ch === '`') {
+      flushSegment()
+      quote = commandSub.resumeQuote
+      commandSub = null
+      continue
+    }
+    if (commandSub?.kind === '$(' && ch === '$' && command[i + 1] === '(') {
+      flushSegment()
+      commandSub.depth++
+      i++
+      continue
+    }
+    if (commandSub?.kind === '$(' && ch === '(') {
+      flushSegment()
+      commandSub.depth++
+      continue
+    }
+    if (commandSub?.kind === '$(' && ch === ')') {
+      flushSegment()
+      commandSub.depth--
+      if (commandSub.depth === 0) {
+        quote = commandSub.resumeQuote
+        commandSub = null
+      }
+      continue
+    }
+    if (ch === '\\') {
+      const next = command[i + 1]
+      if (next === undefined) break
+      // `\<newline>` (and `\<CR><newline>`) is a shell line continuation: the
+      // shell removes it entirely, joining the surrounding text. Dropping it
+      // here keeps `npm install \<nl>-g x` tokenized as `install`,`-g` (a global
+      // install) instead of producing a malformed `install\n-g` token.
+      if (next === '\n') {
+        i++
+        continue
+      }
+      if (next === '\r' && command[i + 2] === '\n') {
+        i += 2
+        continue
+      }
+      current += next
+      hasWord = true
+      i++
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      hasWord = true
+      continue
+    }
+    if (ch === ' ' || ch === '\t') {
+      flushWord()
+      continue
+    }
+    if (ch === '\n' || ch === '\r' || ch === ';' || ch === '|' || ch === '&' || ch === '(' || ch === '`') {
+      flushSegment()
+      continue
+    }
+    if (ch === '$' && command[i + 1] === '(') {
+      flushSegment()
+      i++
+      continue
+    }
+    current += ch
+    hasWord = true
+  }
+  flushSegment()
+  return segments
+}
+
+// A word is already quote/escape-collapsed by splitSegments (quotes consumed,
+// backslash-escapes literalized), so the only residue to strip is leftover
+// quote characters that appeared mid-token via concatenation. Keeping this
+// explicit makes `"npm"`, `n\px`, `'npm'` all resolve to their bare binary.
+function normalizeWord(word: string): string {
+  return word.replaceAll('"', '').replaceAll("'", '')
+}
+
+// Preamble wrappers that prefix a real command (`sudo npm …`, `env FOO=bar npm
+// …`, `nice -n 10 npm …`). The value is the set of SHORT option letters that
+// consume the FOLLOWING word as their argument, so `sudo -u nobody npm` skips
+// `nobody` too. Long `--opt=value` forms are self-contained (one token); bare
+// long `--opt` and unknown short flags are skipped as a single token (the safe
+// default — at worst we skip one extra token and still find the manager later).
+const PREAMBLE_WRAPPERS: Record<string, ReadonlySet<string>> = {
+  sudo: new Set(['u', 'g', 'h', 'p', 'C', 'r', 't', 'T', 'U']),
+  env: new Set(['u', 'C', 'S']),
+  nice: new Set(['n']),
+  command: new Set([]),
+  exec: new Set(['a']),
+  nohup: new Set([]),
+  stdbuf: new Set(['i', 'o', 'e']),
+  setsid: new Set([]),
+  time: new Set(['o', 'f']),
+  xargs: new Set([]),
+}
+
+// The command word is the first token that is not a shell preamble: a known
+// wrapper (with its options consumed), or a `VAR=val` assignment. This is what
+// makes `FOO=bar npm install` and `env -i npm install` / `sudo -u nobody pnpm
+// add` resolve to the real manager instead of evading the guard.
+function leadingCommandWord(words: string[]): string | undefined {
+  let i = 0
+  while (i < words.length) {
+    const word = words[i]
+    if (word === undefined) break
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) {
+      i++
+      continue
+    }
+    const argTakingShortOpts = PREAMBLE_WRAPPERS[word]
+    if (argTakingShortOpts !== undefined) {
+      i = skipWrapperOptions(words, i + 1, argTakingShortOpts)
+      continue
+    }
+    return word
+  }
+  return undefined
+}
+
+// From the token after a wrapper, skip its option tokens. A long `--opt` is one
+// token. A short `-x` (or bundled `-xy`) consumes the next word only when its
+// LAST letter is in `argTaking` (e.g. `-n 10`, `-u nobody`). `VAR=val` between a
+// wrapper and its command (as `env` allows) is also skipped. Stops at the first
+// non-option, non-assignment token — that is the wrapped command word.
+function skipWrapperOptions(words: string[], start: number, argTaking: ReadonlySet<string>): number {
+  let i = start
+  while (i < words.length) {
+    const word = words[i]
+    if (word === undefined) break
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word)) {
+      i++
+      continue
+    }
+    if (word.startsWith('--')) {
+      i++
+      continue
+    }
+    if (word.startsWith('-') && word.length > 1) {
+      const lastLetter = word[word.length - 1]
+      i++
+      if (lastLetter !== undefined && argTaking.has(lastLetter) && i < words.length) i++
+      continue
+    }
+    break
+  }
+  return i
+}
+
+function globalInstallLabel(manager: string, words: string[]): string | undefined {
+  if (manager === 'yarn') {
+    // Real syntax is `yarn global add <pkg>` — `global` immediately followed by
+    // `add` as a consecutive sequence. Checking for both tokens anywhere would
+    // false-positive on `yarn add global foo` (a local install of a package
+    // literally named `global`), which is not a global install at all.
+    return hasAdjacentSequence(words, 'global', 'add') ? 'yarn global add' : undefined
+  }
+  const hasInstall = words.some((w) => INSTALL_SUBCOMMANDS.has(w))
+  const hasGlobal = words.some(isGlobalFlag)
+  if (!hasInstall || !hasGlobal) return undefined
+  return manager === 'bun' ? 'bun global install (-g / --global)' : 'npm/pnpm global install (-g / --global)'
+}
+
+function hasAdjacentSequence(words: string[], first: string, second: string): boolean {
+  for (let i = 0; i + 1 < words.length; i++) {
+    if (words[i] === first && words[i + 1] === second) return true
+  }
+  return false
+}
+
+// `-g` / `--global`, including bundled short flags like `-gD` / `-Dg`. An
+// explicit falsy value (`--global=false|0|no|off`) is NOT a global install —
+// it disables the flag — so it must not match.
+function isGlobalFlag(word: string): boolean {
+  if (/^--global=(?:false|0|no|off)$/i.test(word)) return false
+  if (/^--global(?:=|$)/.test(word)) return true
+  return /^-[A-Za-z]*g[A-Za-z]*$/.test(word)
+}
+
+function blockGlobalInstall(label: string, args: Record<string, unknown>): GuardBlock | undefined {
+  if (isGuardAcknowledged(args, GUARD_GLOBAL_INSTALL)) return undefined
+
+  return {
+    block: true,
+    reason: [
+      `Guard \`${GUARD_GLOBAL_INSTALL}\` blocked a global install: ${label}.`,
+      'Global installs live outside the bind-mounted /agent folder and are wiped on every container restart, so they never persist.',
+      'Use `bun add <pkg>` to add a dependency that survives restarts (it writes package.json), or `bunx <pkg>` to run a tool once without installing.',
+      `Retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_GLOBAL_INSTALL}: true\` only if a throwaway global install is genuinely what you want.`,
+    ].join(' '),
+  }
+}
+
+function blockNonBunManager(manager: string, args: Record<string, unknown>): GuardBlock | undefined {
+  if (isGuardAcknowledged(args, GUARD_NON_BUN_PACKAGE_MANAGER)) return undefined
+
+  return {
+    block: true,
+    reason: [
+      `Guard \`${GUARD_NON_BUN_PACKAGE_MANAGER}\` blocked \`${manager}\`. This container standardizes on bun.`,
+      'Use `bun install` / `bun add <pkg>` instead of npm/pnpm/yarn, and `bunx <pkg>` instead of npx/pnpx.',
+      `Retry with \`${ACKNOWLEDGE_GUARDS}.${GUARD_NON_BUN_PACKAGE_MANAGER}: true\` if this package manager is genuinely required (e.g. a project pinned to a different lockfile).`,
+    ].join(' '),
+  }
+}

package/src/bundled-plugins/github-cli-auth/gh-command.ts

@@ -1,7 +1,11 @@
 export type GhCommandDecision =
   | { kind: 'pass-through' }
   | { kind: 'block'; reason: string }
-  | { kind: 'inject'; repoSlug: string }
+  // `rewrittenCommand`, when present, MUST replace the executed command: `gh api`
+  // rejects `-R/--repo` ("unknown shorthand flag"), so for a graphql endpoint the
+  // flag is consumed as our repo hint and stripped before exec. Other inject paths
+  // (REST, non-`api` subcommands) leave the command unchanged and omit it.
+  | { kind: 'inject'; repoSlug: string; rewrittenCommand?: string }
 
 const MISSING_REPO_REASON =
   'This GitHub App spans multiple owners, so `gh` has no single correct token. ' +
@@ -27,7 +31,9 @@ const API_REPO_CONFLICT_REASON =
 type GhSegmentDecision =
   | { kind: 'pass-through' }
   | { kind: 'block'; reason: string }
-  | { kind: 'inject'; repoSlugs: readonly string[] }
+  // `stripRepoFlag` marks a graphql inject whose `-R/--repo` is a TypeClaw-only
+  // hint that `gh api` would reject, so it must be removed from the command.
+  | { kind: 'inject'; repoSlugs: readonly string[]; stripRepoFlag?: boolean }
 
 const COMPOSITION_REASON =
   'A repo-targeting `gh` command receives a minted GitHub App token in its process ' +
@@ -117,13 +123,17 @@ export function analyzeGhCommand(command: string): GhCommandDecision {
   if (ghStarts.length === 0) return { kind: 'pass-through' }
 
   const repoSlugs: string[] = []
+  let stripRepoFlag = false
   for (let i = 0; i < ghStarts.length; i++) {
     const start = ghStarts[i] as number
     const end = ghStarts[i + 1] ?? tokens.length
     const args = tokens.slice(start + 1, end)
     const segment = classifyGhSegment(args)
     if (segment.kind === 'block') return segment
-    if (segment.kind === 'inject') repoSlugs.push(...segment.repoSlugs)
+    if (segment.kind === 'inject') {
+      repoSlugs.push(...segment.repoSlugs)
+      if (segment.stripRepoFlag === true) stripRepoFlag = true
+    }
   }
 
   if (repoSlugs.length === 0) return { kind: 'pass-through' }
@@ -135,9 +145,71 @@ export function analyzeGhCommand(command: string): GhCommandDecision {
   // shell expansion would inherit it.
   if (!isSingleBareGhCommand(command)) return { kind: 'block', reason: COMPOSITION_REASON }
 
+  if (stripRepoFlag) {
+    return { kind: 'inject', repoSlug: repoSlugs[0] as string, rewrittenCommand: stripRepoFlagFromCommand(command) }
+  }
   return { kind: 'inject', repoSlug: repoSlugs[0] as string }
 }
 
+// Removes an unquoted `-R`/`--repo` flag (and its repo-slug value) from a single
+// bare command, preserving everything else byte-for-byte. Quote-aware so a `-R`
+// inside a quoted `-f query='...'` value is never touched; a repo slug is
+// owner/name (no whitespace), so the value is always a single unquoted token.
+// Used only for graphql, where `gh api` rejects the flag we consumed as a hint.
+function stripRepoFlagFromCommand(command: string): string {
+  let out = ''
+  let i = 0
+  while (i < command.length) {
+    const ch = command[i] as string
+    if (ch === '"' || ch === "'") {
+      const close = command.indexOf(ch, i + 1)
+      const endQuote = close === -1 ? command.length : close
+      out += command.slice(i, endQuote + 1)
+      i = endQuote + 1
+      continue
+    }
+    const removed = matchRepoFlagAt(command, i)
+    if (removed !== null) {
+      out = out.replace(/[ \t]+$/, '')
+      i = removed
+      while (command[i] === ' ' || command[i] === '\t') i += 1
+      if (out !== '' && i < command.length) out += ' '
+      continue
+    }
+    out += ch
+    i += 1
+  }
+  return out
+}
+
+// If `command` has an unquoted `-R`/`--repo` repo-flag token starting at `start`
+// (at a word boundary), returns the index just past the flag and its value;
+// otherwise null. Handles `-R o/r`, `--repo o/r`, `-R=o/r`, `--repo=o/r`.
+function matchRepoFlagAt(command: string, start: number): number | null {
+  const before = start === 0 ? '' : (command[start - 1] as string)
+  if (before !== '' && before !== ' ' && before !== '\t') return null
+
+  for (const flag of ['--repo', '-R']) {
+    if (!command.startsWith(flag, start)) continue
+    let i = start + flag.length
+    const sep = command[i]
+    if (sep === '=') {
+      i += 1
+      while (i < command.length && command[i] !== ' ' && command[i] !== '\t') i += 1
+      return i
+    }
+    if (sep === ' ' || sep === '\t') {
+      let j = i
+      while (command[j] === ' ' || command[j] === '\t') j += 1
+      const valueStart = j
+      while (j < command.length && command[j] !== ' ' && command[j] !== '\t') j += 1
+      if (!isRepoSlug(command.slice(valueStart, j))) return null
+      return j
+    }
+  }
+  return null
+}
+
 function classifyGhSegment(args: readonly string[]): GhSegmentDecision {
   const subcommand = args.find((t) => !t.startsWith('-'))
   if (subcommand === undefined) return { kind: 'pass-through' }
@@ -159,8 +231,9 @@ function classifyGhSegment(args: readonly string[]): GhSegmentDecision {
 // Repo authority for `gh api`: the literal endpoint path wins. A `-R/--repo`
 // that names a DIFFERENT repo than the path is a mint-for-X-but-hit-Y attempt
 // and blocks. A placeholder endpoint (`repos/{owner}/{repo}`) has no literal
-// target, so -R fills it and is authoritative. A non-repo endpoint (`graphql`,
-// `/user`) passes through — -R does not make it repo-scoped, so no mint.
+// target, so -R fills it and is authoritative. A non-repo endpoint without a
+// `-R` (`graphql`, `/user`) passes through — the flag is what makes it
+// repo-scoped, so absent one there is nothing to mint for.
 function classifyGhApiSegment(args: readonly string[]): GhSegmentDecision {
   const pathRepos = extractReposFromApiPath(args)
   const flagRepo = extractRepoFlag(args)
@@ -176,9 +249,22 @@ function classifyGhApiSegment(args: readonly string[]): GhSegmentDecision {
     return { kind: 'inject', repoSlugs: [flagRepo] }
   }
 
+  // graphql encodes its repo in the query body / opaque node IDs, never an
+  // inspectable path, so `-R` is taken as the mint hint. Safe because there is
+  // no literal path to conflict with (cf. the API_REPO_CONFLICT_REASON guard
+  // above): the minted token's installation scope, not the flag, bounds reach.
+  // `gh api` rejects `-R`, so the flag must be stripped from the command.
+  if (flagRepo !== null && isGraphqlEndpoint(args)) {
+    return { kind: 'inject', repoSlugs: [flagRepo], stripRepoFlag: true }
+  }
+
   return { kind: 'pass-through' }
 }
 
+function isGraphqlEndpoint(args: readonly string[]): boolean {
+  return findApiEndpoint(args) === 'graphql'
+}
+
 function findGhInvocations(tokens: readonly string[]): number[] {
   const starts: number[] = []
   for (let i = 0; i < tokens.length; i++) {
@@ -249,6 +335,12 @@ const GH_API_VALUE_FLAGS = new Set([
   '--hostname',
 ])
 
+// `-R`/`--repo` are not real `gh api` flags, but TypeClaw accepts them as a repo
+// hint that can appear BEFORE the endpoint (`gh api -R o/r graphql`). They consume
+// the following token, so findApiEndpoint must skip both — otherwise the slug is
+// misread as the endpoint and the graphql path never runs.
+const REPO_HINT_VALUE_FLAGS = new Set(['-R', '--repo'])
+
 // The `gh api` endpoint is the first positional arg after `api` (skipping flags
 // and the tokens that bare value-flags consume). Returns null if there is none.
 function findApiEndpoint(args: readonly string[]): string | null {
@@ -257,7 +349,7 @@ function findApiEndpoint(args: readonly string[]): string | null {
   for (let i = apiIndex + 1; i < args.length; i++) {
     const arg = args[i] as string
     if (arg.startsWith('-')) {
-      if (!arg.includes('=') && GH_API_VALUE_FLAGS.has(arg)) i += 1
+      if (!arg.includes('=') && (GH_API_VALUE_FLAGS.has(arg) || REPO_HINT_VALUE_FLAGS.has(arg))) i += 1
       continue
     }
     return arg

package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts

@@ -0,0 +1,80 @@
+import type { ContentPart, ToolResult } from '@/plugin'
+
+import { classifyGhToken } from './token-class'
+
+export const GRAPHQL_AUTH_NUDGE_TAG = 'github-cli-auth:graphqlRepoHint'
+
+const NUDGE_TEXT =
+  `\n\n[${GRAPHQL_AUTH_NUDGE_TAG}] That looked like a GitHub auth failure on a ` +
+  '`gh api graphql` call. Under a multi-owner GitHub App there is no single ' +
+  '`GH_TOKEN`, and graphql carries its repo inside the query — not an inspectable ' +
+  'path — so TypeClaw cannot tell which installation token to mint. Re-run with an ' +
+  'explicit repo, e.g. `gh api graphql -R owner/repo -f query=...`. `gh api` does ' +
+  'not accept `-R/--repo`; TypeClaw consumes it as the mint hint and strips it ' +
+  'before running the command with the right token injected.'
+
+// The shell strips quotes/escapes, so we match the raw `gh ... graphql` substring
+// rather than parse — the nudge is advisory, so a loose match is acceptable and a
+// false positive only appends a hint to an unrelated failure. Captured through to
+// end of line so we can inspect the SAME invocation's flags (see REPO_FLAG).
+const GRAPHQL_INVOCATION = /\bgh\b[^\n]*\bapi\b[^\n]*\bgraphql\b[^\n]*/
+
+// `-R foo`, `-R=foo`, `--repo foo`, `--repo=foo`. Word-boundary anchored so a
+// path or token merely containing "repo" does not count as a repo hint.
+const REPO_FLAG = /(?:^|\s)(?:-R|--repo)(?:[=\s]|$)/
+
+// Concrete auth-rejection strings only — gh / the API emit these when the
+// request itself was rejected for auth. Deliberately excludes resolution
+// errors like "Could not resolve to ...", which graphql also returns for an
+// ordinary bad node ID or missing repo (not auth) and would misroute the nudge.
+const AUTH_FAILURE_SIGNATURES = [
+  'HTTP 401',
+  'Bad credentials',
+  'Resource not accessible by integration',
+  'Resource not accessible by personal access token',
+  'must be authenticated',
+  'authentication required',
+  'gh auth login',
+]
+
+export function checkGraphqlAuthNudge(options: { tool: string; result: ToolResult }): void {
+  if (options.tool !== 'bash') return
+
+  // Only meaningful when no usable token is seeded — the multi-owner App case.
+  // A seeded global token (single-owner App, classic/fine-grained PAT) means
+  // graphql already authenticates, so the advice would be wrong.
+  const tokenClass = classifyGhToken(process.env.GH_TOKEN)
+  if (tokenClass !== 'none') return
+
+  const text = collectText(options.result.content)
+  const invocation = GRAPHQL_INVOCATION.exec(text)
+  if (invocation === null) return
+  if (!AUTH_FAILURE_SIGNATURES.some((sig) => text.includes(sig))) return
+  if (text.includes(GRAPHQL_AUTH_NUDGE_TAG)) return
+
+  // The nudge's only message is "add the repo hint". If the failing invocation
+  // already carries -R/--repo, the hint is present and the failure is an
+  // authorization/permission denial (e.g. the App token lacks a scope), not a
+  // missing-repo one — so "re-run with -R" would be misleading, repeated advice.
+  if (REPO_FLAG.test(invocation[0])) return
+
+  appendAdviceToContent(options.result.content, NUDGE_TEXT)
+}
+
+function collectText(content: readonly ContentPart[]): string {
+  return content
+    .filter((p): p is ContentPart & { type: 'text' } => p.type === 'text')
+    .map((p) => p.text)
+    .join('\n')
+}
+
+function appendAdviceToContent(content: ContentPart[], advice: string): void {
+  for (let i = content.length - 1; i >= 0; i--) {
+    const part = content[i]
+    if (part && part.type === 'text') {
+      content[i] = { ...part, text: `${part.text}${advice}` }
+      return
+    }
+  }
+  content.push({ type: 'text', text: advice.trimStart() })
+}

package/src/bundled-plugins/github-cli-auth/index.ts

@@ -2,6 +2,7 @@ import { TYPECLAW_INTERNAL_BASH_ENV } from '@/agent/plugin-tools'
 import { definePlugin } from '@/plugin'
 
 import { analyzeGhCommand } from './gh-command'
+import { checkGraphqlAuthNudge } from './graphql-auth-nudge'
 import { classifyGhToken } from './token-class'
 
 export default definePlugin({
@@ -34,8 +35,14 @@ export default definePlugin({
           // --setenv by the bash wrapper) so the token never enters the command
           // string, where it could leak through logs or later hooks.
           event.args[TYPECLAW_INTERNAL_BASH_ENV] = { GH_TOKEN: result.token }
+          // graphql consumed `-R/--repo` as a mint hint; `gh api` rejects it, so
+          // run the command with the flag stripped (token still rides in env).
+          if (decision.rewrittenCommand !== undefined) event.args.command = decision.rewrittenCommand
           return
         },
+        'tool.after': async (event) => {
+          checkGraphqlAuthNudge({ tool: event.tool, result: event.result })
+        },
       },
     }
   },

package/src/bundled-plugins/memory/memory-logger.ts

@@ -81,9 +81,11 @@ Session transcripts are JSONL files where each line is an entry with an \`id\` f
 Typical flow with a watermark:
 
 1. \`find_entry(path=<transcript>, entryId=<watermark>)\` → returns \`line=N, totalLines=T, offset=N+1\`.
-2. \`read(path=<transcript>, offset=N+1)\` → returns the chunk starting AT the first unread entry. Repeat with the next offset until the read tool's continuation notice stops appearing.
+2. \`read(path=<transcript>, offset=N+1)\` → returns the chunk starting AT the first unread entry. Repeat with the next offset until you reach the end of the file. \`find_entry\` already told you \`totalLines=T\`: once a \`read\` has returned line T (or the read tool reports no continuation), you have reached the end of the transcript. Stop reading.
 3. As you read, track the most recent \`id\` you see. That is your new watermark value — pass it as \`latestEntryId\` on the final \`append\` call, or to the watermark-advance tool when there are zero fragments.
 
+**Reading is bounded — a finite transcript takes a finite number of reads.** \`find_entry\` gives you \`totalLines=T\` up front, so you always know the last line. Each \`read\` returns a slice and an offset to continue; advance the offset forward each time. Once you have read line T, or a \`read\` returns no new content (an empty chunk, or the same slice you already saw, or no continuation offset), you are at the end. Do NOT re-read the same offset, and do NOT keep calling \`read\` hoping more will appear — nothing more will. A read that returns nothing new is the end-of-file signal, not a transient error to retry. Re-reading past the end produces no new information and wastes the entire run; treat the first no-new-content read as "done reading" and move to your fragment decision.
+
 Never write the same watermark id you were given as input. If the transcript has no new entries past the watermark, evaluate the entries you can see, then advance the watermark to the latest \`id\` in the transcript (which is on line \`totalLines\` from \`find_entry\`'s reply). The whole point of the watermark is to move forward each run.
 
 # Capture philosophy: when in doubt, SKIP
@@ -202,7 +204,9 @@ When you evaluated the transcript but found nothing worth a fragment, call the w
 
 # Stopping
 
-When you're done, simply stop. There is no completion message to emit.`
+You are done the moment BOTH are true: (1) you have read to the end of the transcript (reached \`totalLines\` from \`find_entry\`, or a \`read\` returned no new content), and (2) you have either written your fragment(s) with the final \`latestEntryId\`, or advanced the watermark for the zero-fragment case. When both hold, simply stop. There is no completion message to emit.
+
+Do not loop. The hard stop is \`totalLines\`: a long transcript may legitimately need many \`read\` chunks to reach it, and that is fine as long as each \`read\` advances the offset toward \`totalLines\`. What is NOT fine is re-reading without progress. If a \`read\` returns no new content, returns the same slice you already saw, or your offset stops advancing, you are at the end — stop reading immediately and proceed to your fragment decision. A transcript has a fixed length; re-reading the same offset cannot surface content that is not there. The single most expensive failure mode for this subagent is re-reading the same file in a cycle instead of recognizing end-of-file and stopping.`
 
 function buildInitialPrompt(payload: MemoryLoggerPayload, streamFile: string, watermark: string | null): string {
   const lines: string[] = [

package/src/bundled-plugins/reviewer/skills/code-review.ts

@@ -64,6 +64,14 @@ Prioritize in this order:
 - **request-changes** — At least one blocker, OR a load-bearing concern that needs an answer before this lands.
 - **comment** — Mixed signal: useful observations without a clear approve/reject. Common on large refactors where you reviewed part of the change, or on early-draft PRs where the author asked for direction more than approval.
 
+### Re-reviews must re-decide, not observe
+
+When the payload tells you this is a **re-review** — you (or this agent) previously requested changes on this PR and the author has pushed fixes and asked again — your verdict's whole purpose is to **re-decide the blocking state**, so:
+
+- Return **approve** if the blockers that drove the prior \`request-changes\` are resolved (leftover nits do not block — \`approve\` with inline nits is correct).
+- Return **request-changes** if any blocker remains or a new one appeared.
+- **Do NOT return \`comment\` on a re-review.** \`comment\` is for ambiguous partial reviews with no accept/reject signal; a re-review is the opposite — it is precisely an accept/reject decision. A \`comment\` verdict here leaves the PR's \`REQUEST_CHANGES\` state stuck (a plain comment does not clear it on GitHub), which is the exact failure a re-review exists to resolve. The only escape hatch is the same one that always applies: if you genuinely cannot reach the diff or the prior context, return one \`blocker\` finding stating what you need and a \`comment\` verdict — but a reachable, reviewable re-review must end in \`approve\` or \`request-changes\`.
+
 ## Line-anchor every finding
 
 Code review is line-level work, and your findings are meant to land as **inline comments on the exact lines they describe**. The parent agent posts them that way — it reads the \`location\` on each \`<finding>\` and attaches your \`<issue>\`/\`<evidence>\`/\`<suggestion>\` to that line. A finding with no line anchor cannot be posted inline; the parent can only fold it into a top-level summary, which strips the one thing that made it actionable.

package/src/channels/adapters/discord-bot.ts

@@ -52,6 +52,8 @@ import {
 const SLASH_COMMANDS: readonly DiscordCommandDeclaration[] = [
   { name: 'help', description: 'List available commands' },
   { name: 'stop', description: 'Abort the current turn in this channel' },
+  { name: 'reload', description: 'Reload typeclaw config and subsystems from disk' },
+  { name: 'restart', description: 'Restart the typeclaw container' },
 ]
 const SLASH_COMMAND_NAMES: ReadonlySet<string> = new Set(SLASH_COMMANDS.map((c) => c.name))