typeclaw 0.10.0 → 0.11.0

package/src/run/codex-fetch-observer.ts

@@ -0,0 +1,377 @@
+export type CodexFetchObserverLogger = {
+  info: (msg: string) => void
+  warn: (msg: string) => void
+}
+
+export type CodexFetchObserverOptions = {
+  logger?: CodexFetchObserverLogger
+  codexHost?: string
+  now?: () => number
+  // Override the default pre-headers (TTFB) deadline applied to the outer
+  // fetch(). When the codex backend silently holds a request without sending
+  // response headers, this is the timer that releases the request so
+  // `pi-coding-agent`'s `_isRetryableError` can retry. Default: 15_000 ms.
+  //
+  // Healthy Codex turns return response headers within ~1s (observed
+  // production p50: ~860ms). The first SSE event (`response.created`) is
+  // emitted before any model work begins and arrives within ~50ms of
+  // headers. Pathological-but-healthy upper bounds: TLS handshake on a cold
+  // connection (~2s), prompt-prefill on a cache miss with large input
+  // (~3s), Cloudflare PoP routing slowness (~2s) — sum ~7s. 15s is ~2x
+  // that, so anything past it is almost certainly the silent-hang failure
+  // mode rather than a real request making progress. False-positive cost
+  // is one retry (~5s extra); false-negative cost is the full Bun socket
+  // deadline (~268s). Aggressive wins.
+  ttfbMs?: number
+  // Override the sliding inter-chunk idle deadline applied to the SSE body
+  // reader. Resets on every chunk; if no bytes arrive within this window the
+  // body stream errors. Default: 300_000 ms, matches `openai/codex`'s Rust CLI
+  // `DEFAULT_STREAM_IDLE_TIMEOUT_MS`. Set to 0 to disable just this timer.
+  idleMs?: number
+  // Schedule fn for tests. Receives (delayMs, callback) and returns a handle
+  // the wrapper can pass to `clear`. Default: `setTimeout`/`clearTimeout`.
+  scheduler?: TimeoutScheduler
+}
+
+export type TimeoutScheduler = {
+  set: (delayMs: number, cb: () => void) => unknown
+  clear: (handle: unknown) => void
+}
+
+const DEFAULT_CODEX_HOST = 'chatgpt.com'
+const CODEX_PATH_FRAGMENT = '/codex/responses'
+const ENV_DISABLE_OBSERVER = 'TYPECLAW_CODEX_FETCH_OBSERVER'
+const ENV_DISABLE_TIMEOUTS = 'TYPECLAW_CODEX_TIMEOUTS'
+const ENV_TTFB_MS = 'TYPECLAW_CODEX_TTFB_MS'
+const ENV_IDLE_MS = 'TYPECLAW_CODEX_IDLE_MS'
+const DEFAULT_TTFB_MS = 15_000
+const DEFAULT_IDLE_MS = 300_000
+const LOG_PREFIX = '[codex-fetch]'
+
+const defaultScheduler: TimeoutScheduler = {
+  set: (delayMs, cb) => setTimeout(cb, delayMs),
+  clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+}
+
+const consoleLogger: CodexFetchObserverLogger = {
+  info: (m) => console.log(m),
+  warn: (m) => console.warn(m),
+}
+
+type InstallState = {
+  originalFetch: typeof fetch
+  uninstall: () => void
+}
+
+let installed: InstallState | null = null
+
+// Returns true when the request is for the Codex Responses endpoint and we
+// should attach phase-timing instrumentation. Method check matches the
+// pi-ai provider (only POST hits codex/responses); GETs to the same host
+// (auth probes, etc.) are deliberately ignored.
+function shouldObserve(input: RequestInfo | URL, init: RequestInit | undefined, codexHost: string): boolean {
+  const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase()
+  if (method !== 'POST') return false
+  let urlString: string
+  if (typeof input === 'string') urlString = input
+  else if (input instanceof URL) urlString = input.toString()
+  else urlString = input.url
+  let parsed: URL
+  try {
+    parsed = new URL(urlString)
+  } catch {
+    return false
+  }
+  if (parsed.hostname !== codexHost) return false
+  return parsed.pathname.includes(CODEX_PATH_FRAGMENT)
+}
+
+function quote(value: string | null): string {
+  if (value === null) return 'null'
+  return `"${value.replace(/"/g, '\\"')}"`
+}
+
+function formatLine(fields: {
+  status: number | null
+  headersMs: number | null
+  firstByteMs: number | null
+  totalMs: number
+  bodyBytes: number
+  retryAfter: string | null
+  requestId: string | null
+  error: string | null
+  cause: string | null
+}): string {
+  return [
+    LOG_PREFIX,
+    `status=${fields.status === null ? 'null' : fields.status}`,
+    `headers_ms=${fields.headersMs === null ? 'null' : fields.headersMs}`,
+    `first_byte_ms=${fields.firstByteMs === null ? 'null' : fields.firstByteMs}`,
+    `total_ms=${fields.totalMs}`,
+    `body_bytes=${fields.bodyBytes}`,
+    `retry_after=${fields.retryAfter === null ? 'null' : fields.retryAfter}`,
+    `request_id=${fields.requestId === null ? 'null' : fields.requestId}`,
+    `error=${quote(fields.error)}`,
+    `cause=${fields.cause === null ? 'null' : fields.cause}`,
+  ].join(' ')
+}
+
+function readEnvMs(name: string, fallback: number): number {
+  const raw = process.env[name]
+  if (raw === undefined || raw === '') return fallback
+  const parsed = Number.parseInt(raw, 10)
+  if (!Number.isFinite(parsed) || parsed < 0) return fallback
+  return parsed
+}
+
+type BodyTapConfig = {
+  idleMs: number
+  scheduler: TimeoutScheduler
+}
+
+function attachBodyTimingTap(
+  response: Response,
+  start: number,
+  headersMs: number,
+  status: number,
+  retryAfter: string | null,
+  requestId: string | null,
+  now: () => number,
+  logger: CodexFetchObserverLogger,
+  config: BodyTapConfig,
+): Response {
+  if (response.body === null) {
+    logger.info(
+      formatLine({
+        status,
+        headersMs,
+        firstByteMs: null,
+        totalMs: now() - start,
+        bodyBytes: 0,
+        retryAfter,
+        requestId,
+        error: null,
+        cause: null,
+      }),
+    )
+    return response
+  }
+
+  let firstByteMs: number | null = null
+  let bodyBytes = 0
+  let settled = false
+  let cause: string | null = null
+
+  const settle = (error: string | null) => {
+    if (settled) return
+    settled = true
+    logger.info(
+      formatLine({
+        status,
+        headersMs,
+        firstByteMs,
+        totalMs: now() - start,
+        bodyBytes,
+        retryAfter,
+        requestId,
+        error,
+        cause,
+      }),
+    )
+  }
+
+  const tap = new TransformStream<Uint8Array, Uint8Array>({
+    transform(chunk, controller) {
+      if (firstByteMs === null) firstByteMs = now() - start
+      bodyBytes += chunk.byteLength
+      controller.enqueue(chunk)
+    },
+    flush() {
+      settle(null)
+    },
+  })
+
+  const piped = response.body.pipeThrough(tap, { preventCancel: false })
+
+  const idleController = config.idleMs > 0 ? new AbortController() : null
+  let idleHandle: unknown = null
+  const armIdleTimer = () => {
+    if (idleController === null) return
+    if (idleHandle !== null) config.scheduler.clear(idleHandle)
+    idleHandle = config.scheduler.set(config.idleMs, () => {
+      cause = 'idle_timeout'
+      idleController.abort(new Error(`Codex SSE body idle for ${config.idleMs}ms (typeclaw observer timeout)`))
+    })
+  }
+  const disarmIdleTimer = () => {
+    if (idleHandle !== null) {
+      config.scheduler.clear(idleHandle)
+      idleHandle = null
+    }
+  }
+
+  // The idle abort listener is installed exactly once for the lifetime of the
+  // stream and removed in `finally`. Earlier shapes constructed a fresh
+  // `Promise.race` listener per chunk; if `reader.read()` won the race, the
+  // listener was never removed and closures accumulated on the signal across a
+  // long stream. Keeping one shared abort promise bounds the listener count to
+  // 1 regardless of chunk count.
+  const observerBody = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const reader = piped.getReader()
+      armIdleTimer()
+      let abortFired = false
+      let onAbort: (() => void) | null = null
+      const abortPromise = idleController
+        ? new Promise<never>((_, reject) => {
+            onAbort = () => {
+              abortFired = true
+              reject(idleController.signal.reason ?? new Error('idle timeout'))
+            }
+            if (idleController.signal.aborted) onAbort()
+            else idleController.signal.addEventListener('abort', onAbort, { once: true })
+          })
+        : null
+      // Swallow the shared rejection if no race ever observes it (clean stream
+      // end before any timeout). Without this, an aborted-after-close path
+      // could surface as an unhandled rejection on the runtime.
+      abortPromise?.catch(() => {})
+      try {
+        while (true) {
+          const readPromise = reader.read()
+          const result = abortPromise ? await Promise.race([readPromise, abortPromise]) : await readPromise
+          if (abortFired) {
+            reader.cancel(idleController!.signal.reason).catch(() => {})
+            throw idleController!.signal.reason
+          }
+          const { done, value } = result
+          if (done) {
+            disarmIdleTimer()
+            controller.close()
+            return
+          }
+          armIdleTimer()
+          controller.enqueue(value)
+        }
+      } catch (err) {
+        disarmIdleTimer()
+        const message = err instanceof Error ? err.message : String(err)
+        settle(message)
+        controller.error(err)
+      } finally {
+        if (onAbort !== null && idleController !== null && !idleController.signal.aborted) {
+          idleController.signal.removeEventListener('abort', onAbort)
+        }
+        reader.releaseLock()
+      }
+    },
+    cancel(reason) {
+      disarmIdleTimer()
+      const message = reason === undefined ? 'cancelled' : reason instanceof Error ? reason.message : String(reason)
+      settle(message)
+    },
+  })
+
+  return new Response(observerBody, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  })
+}
+
+export function installCodexFetchObserver(opts: CodexFetchObserverOptions = {}): () => void {
+  if (process.env[ENV_DISABLE_OBSERVER] === 'off') {
+    return () => {}
+  }
+  const logger = opts.logger ?? consoleLogger
+  if (installed !== null) {
+    logger.warn(`${LOG_PREFIX} install called but observer already installed; ignoring`)
+    return installed.uninstall
+  }
+
+  const codexHost = opts.codexHost ?? DEFAULT_CODEX_HOST
+  const now = opts.now ?? Date.now
+  const scheduler = opts.scheduler ?? defaultScheduler
+  const timeoutsEnabled = process.env[ENV_DISABLE_TIMEOUTS] !== 'off'
+  const ttfbMs = timeoutsEnabled ? (opts.ttfbMs ?? readEnvMs(ENV_TTFB_MS, DEFAULT_TTFB_MS)) : 0
+  const idleMs = timeoutsEnabled ? (opts.idleMs ?? readEnvMs(ENV_IDLE_MS, DEFAULT_IDLE_MS)) : 0
+  const originalFetch = globalThis.fetch
+
+  const wrappedImpl = async (
+    input: Parameters<typeof fetch>[0],
+    init?: Parameters<typeof fetch>[1],
+  ): Promise<Response> => {
+    if (!shouldObserve(input, init, codexHost)) {
+      return originalFetch(input, init)
+    }
+    const start = now()
+
+    let ttfbCause: 'ttfb_timeout' | null = null
+    let ttfbHandle: unknown = null
+    let initWithSignal: RequestInit | undefined = init
+    if (ttfbMs > 0) {
+      const ttfbController = new AbortController()
+      ttfbHandle = scheduler.set(ttfbMs, () => {
+        ttfbCause = 'ttfb_timeout'
+        ttfbController.abort(
+          new Error(`Codex fetch timed out before response headers after ${ttfbMs}ms (typeclaw observer timeout)`),
+        )
+      })
+      const signal = init?.signal ? AbortSignal.any([init.signal, ttfbController.signal]) : ttfbController.signal
+      initWithSignal = { ...init, signal }
+    }
+
+    let response: Response
+    try {
+      response = await originalFetch(input, initWithSignal)
+    } catch (err) {
+      if (ttfbHandle !== null) scheduler.clear(ttfbHandle)
+      const isTtfbAbort = ttfbCause === 'ttfb_timeout'
+      const surfacedError = isTtfbAbort
+        ? new Error(`Codex fetch timed out before response headers after ${ttfbMs}ms (typeclaw observer timeout)`)
+        : err
+      const message = surfacedError instanceof Error ? surfacedError.message : String(surfacedError)
+      logger.info(
+        formatLine({
+          status: null,
+          headersMs: null,
+          firstByteMs: null,
+          totalMs: now() - start,
+          bodyBytes: 0,
+          retryAfter: null,
+          requestId: null,
+          error: message,
+          cause: ttfbCause,
+        }),
+      )
+      throw surfacedError
+    }
+    if (ttfbHandle !== null) scheduler.clear(ttfbHandle)
+    const headersMs = now() - start
+    const retryAfter = response.headers.get('retry-after')
+    const requestId = response.headers.get('x-request-id')
+    return attachBodyTimingTap(response, start, headersMs, response.status, retryAfter, requestId, now, logger, {
+      idleMs,
+      scheduler,
+    })
+  }
+
+  // Preserve any static methods Bun attaches to `globalThis.fetch` (e.g.
+  // `preconnect`) so the wrapper is a drop-in replacement.
+  const wrapped = Object.assign(wrappedImpl, {
+    preconnect: (originalFetch as { preconnect?: (url: string) => void }).preconnect ?? (() => {}),
+  }) as typeof fetch
+
+  globalThis.fetch = wrapped
+
+  const uninstall = () => {
+    if (installed === null) return
+    if (globalThis.fetch === wrapped) {
+      globalThis.fetch = originalFetch
+    }
+    installed = null
+  }
+
+  installed = { originalFetch, uninstall }
+  return uninstall
+}

package/src/run/index.ts

@@ -59,11 +59,12 @@ import { createTunnelManager, type TunnelManager, type TunnelManagerOptions } fr
 
 import { BUNDLED_PLUGINS } from './bundled-plugins'
 import { buildChannelSessionFactory } from './channel-session-factory'
+import { installCodexFetchObserver } from './codex-fetch-observer'
 import { createPluginRuntime, type PluginRuntime, type PluginSubagentEntry } from './plugin-runtime'
 
 type BunServer = ReturnType<Server['start']>
 
-export type TuiFactory = (options: TuiOptions) => { run: () => Promise<void> }
+export type TuiFactory = (options: TuiOptions) => { run: () => Promise<unknown> }
 
 export type LoadCronFn = (agentDir: string, options?: { subagents?: SubagentRegistry }) => Promise<LoadCronResult>
 export type SchedulerFactory = (options: { cwd: string; file: CronFile; onFire: (job: CronJob) => void }) => Scheduler
@@ -86,7 +87,7 @@ export type StartAgentOptions = {
 
 export type StartAgentResult = {
   server: BunServer
-  tuiPromise: Promise<void> | null
+  tuiPromise: Promise<unknown> | null
   scheduler: Scheduler | null
   cronConsumer: CronConsumer | null
   subagentConsumer: SubagentConsumer
@@ -113,6 +114,14 @@ export async function startAgent({
 }: StartAgentOptions): Promise<StartAgentResult> {
   const reloadRegistry = new ReloadRegistry()
 
+  // Wrap globalThis.fetch BEFORE any plugin/session/manager construction so
+  // every Codex Responses call from anywhere in the container is observed.
+  // Logs one `[codex-fetch]` line per matched request with phase timings;
+  // never aborts, never retries — purely passive instrumentation while we
+  // investigate the recurring multi-minute Codex stalls (see issue #394).
+  // Opt out with TYPECLAW_CODEX_FETCH_OBSERVER=off.
+  const uninstallCodexFetchObserver = installCodexFetchObserver()
+
   // The host CLI sets TYPECLAW_CONTAINER_NAME when it `docker run`s us. When
   // running outside a typeclaw container (tests, ad-hoc `bun run typeclaw run`
   // outside docker), the env var is absent and the `restart` tool is omitted —
@@ -585,6 +594,7 @@ export async function startAgent({
     subagentCompletionBridge.stop()
     await tunnelManager.stop()
     await channelManager.stop()
+    uninstallCodexFetchObserver()
   }
 
   if (!attachTui) {

package/src/server/index.ts

@@ -1,3 +1,4 @@
+import { SessionManager } from '@mariozechner/pi-coding-agent'
 import type { Server as BunServer, ServerWebSocket } from 'bun'
 
 import {
@@ -10,6 +11,7 @@ import { runPluginDoctorChecks, runPluginDoctorFix } from '@/agent/doctor'
 import type { LiveSessionRegistry } from '@/agent/live-sessions'
 import type { LiveSubagentRegistry } from '@/agent/live-subagents'
 import { detectProviderError } from '@/agent/provider-error'
+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'
@@ -233,6 +235,42 @@ export function createServer({
 }: ServerOptions) {
   const sessionStates = new WeakMap<Ws, SessionState>()
   const callIdToWs = new Map<string, AnyOwnerWs>()
+
+  // The first TUI WS open per container lifetime checks for
+  // `.typeclaw/restart-pending.json`; subsequent opens see null. The
+  // in-flight promise serializes concurrent first-opens — two TUIs
+  // reconnecting at the same instant share the single consume() call rather
+  // than each racing to reopen the originator's JSONL. Once the promise
+  // resolves, the handoff is consumed exactly once: subsequent opens see
+  // `handoffPending === false` and return null without checking the file.
+  let handoffInFlight: Promise<RestartHandoff | null> | null = null
+  let handoffPending = true
+  async function takeRestartHandoff(): Promise<RestartHandoff | null> {
+    if (!handoffPending) return null
+    if (handoffInFlight !== null) return handoffInFlight
+    if (agentDir === undefined) {
+      handoffPending = false
+      return null
+    }
+    handoffInFlight = consumeRestartHandoff(agentDir).catch(() => null)
+    const result = await handoffInFlight
+    handoffPending = false
+    handoffInFlight = null
+    return result
+  }
+
+  function resumeFromHandoff(handoff: RestartHandoff, factory: SessionFactory | undefined): SessionManager | null {
+    if (factory === undefined) return null
+    const sessionPath = `${factory.sessionDir()}/${handoff.originatingSessionFile}`
+    try {
+      return SessionManager.open(sessionPath)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      logger.warn(`restart-handoff: failed to reopen ${sessionPath}: ${message}`)
+      return null
+    }
+  }
+
   const commandRunner: CommandRunner | undefined = commandRunnerFactory
     ? commandRunnerFactory({
         stdout(callId, chunk) {
@@ -397,7 +435,9 @@ export function createServer({
           if (rawWs.data.kind === 'inspect') return
           const ws = rawWs as Ws
           try {
-            const sessionManager = sessionFactory?.createPersisted()
+            const handoff = await takeRestartHandoff()
+            const resumed = handoff !== null ? resumeFromHandoff(handoff, sessionFactory) : null
+            const sessionManager = resumed ?? sessionFactory?.createPersisted()
             const sessionFileId = sessionManager?.getSessionId() ?? ws.data.sessionId
             // Snapshot the runtime once so the entire session lifecycle for this
             // ws connection sees one consistent generation of registry+hooks. A
@@ -485,6 +525,24 @@ export function createServer({
               ...(runtimeVersion !== undefined ? { serverVersion: runtimeVersion } : {}),
             })
             console.log(`session ${sessionFileId}: open`)
+
+            // Fire the post-restart kick. The originator's JSONL already
+            // contains the `typeclaw.restart-self` custom message entry that
+            // the dying container appended (see subscribeRestartNotice in
+            // src/agent/index.ts). pi's buildSessionContext() hydrates that
+            // entry as a `role: "user"` LLM message on the next prompt, so
+            // a single-space kick is enough to trigger a turn — the entry's
+            // own text instructs the model to "briefly confirm the restart
+            // completed". Publish AFTER the session-target subscription is
+            // wired (state.unsubPrompts above) so the kick is enqueued, not
+            // dropped on the floor.
+            if (resumed !== null && stream) {
+              stream.publish({
+                target: { kind: 'session', sessionId: sessionFileId },
+                payload: { kind: 'prompt', text: ' ', delivery: 'queue' },
+                meta: { source: 'restart-handoff' },
+              })
+            }
           } catch (err) {
             const message = err instanceof Error ? err.message : String(err)
             console.error(`session ${ws.data.sessionId}: open failed: ${message}`)

package/src/shared/protocol.ts

@@ -28,7 +28,7 @@ export type TunnelRequestId = string
 
 export type TunnelSnapshot = {
   name: string
-  provider: 'external' | 'cloudflare-quick'
+  provider: 'external' | 'cloudflare-quick' | 'cloudflare-named'
   for: { kind: 'channel'; name: string } | { kind: 'manual' }
   url: string | null
   status: 'stopped' | 'starting' | 'healthy' | 'unhealthy' | 'permanently-failed'

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`. 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. 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 an inbound says "requested your review on PR #N" or "requested a review from team @… on PR #N" (the agent has been assigned as a reviewer and must do a real code review with line-by-line comments 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. 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.
@@ -22,3 +22,47 @@ gh pr create --repo owner/repo --title "Fix: ..." --head my-branch --base main -
 ```
 
 For App auth, `GH_TOKEN` is an installation access token that refreshes automatically — it stays current as long as the adapter is running.
+
+## Reviewing pull requests
+
+When an incoming message says **"requested your review on PR #N"** (or "requested a review from team @… on PR #N"), you have been assigned as a reviewer. Do a real code review and post line-by-line comments via `gh api`. Do **not** just reply in the channel — the user wants feedback on the diff.
+
+### Workflow
+
+1. **Read the diff and context**:
+
+   ```sh
+   gh pr diff <N> --repo owner/repo
+   gh pr view <N> --repo owner/repo --json title,body,baseRefName,headRefOid,files
+   ```
+
+2. **Submit a multi-comment review** in one API call. `comments[]` accepts line-level entries; each one lands on the diff exactly like a human reviewer's inline comment:
+
+   ```sh
+   gh api -X POST /repos/owner/repo/pulls/<N>/reviews \
+     -F event=COMMENT \
+     -f body="Overall: looks good with a few nits." \
+     -F 'comments[][path]=src/foo.ts' \
+     -F 'comments[][line]=42' \
+     -F 'comments[][side]=RIGHT' \
+     -F 'comments[][body]=nit: prefer `const` here.' \
+     -F 'comments[][path]=src/bar.ts' \
+     -F 'comments[][line]=10' \
+     -F 'comments[][side]=RIGHT' \
+     -F 'comments[][body]=Consider extracting this branch into a helper.'
+   ```
+
+3. **Then** post a one-line summary with `channel_reply` so the conversation has a human-readable trace pointing at the review.
+
+### Rules
+
+- Use `event=COMMENT` by default. Use `APPROVE` only when you have high confidence the PR is ready to merge. Use `REQUEST_CHANGES` only when the PR has clear blockers — not for nits.
+- `line` is a line number **in the file**, not a position in the diff. `side: RIGHT` is the new revision (default for additions); `side: LEFT` is the old revision (use for comments on removed lines).
+- For multi-line comments, also set `start_line` and `start_side` (same semantics).
+- If you need to read whole files at the PR's head SHA, use `gh api /repos/owner/repo/contents/<path>?ref=<headRefOid>`.
+- 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.
+- A `review_request_removed` event means the requester un-assigned you. Stop any in-progress review work; do not post a partial review.
+
+### Self-loop safety
+
+The adapter will **not** wake you when you assign yourself as a reviewer (e.g., via `gh pr edit --add-reviewer`). It will only wake you when someone else requests your review.

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

@@ -30,6 +30,27 @@ Choose Cloudflare Quick when the user wants the easiest path:
 
 For GitHub channel setup, `typeclaw channel add github` can write a channel-owned Cloudflare Quick tunnel named `github-webhook` and set `docker.file.cloudflared: true`. The first `typeclaw start` or `restart` after that rebuilds the image with `cloudflared` installed.
 
+### Cloudflare Named Tunnel
+
+Choose Cloudflare Named when the user has a domain on Cloudflare and wants a stable URL:
+
+- Cloudflare account required (free), plus a domain already in their account's `Websites` list.
+- The user creates the tunnel in the Zero Trust dashboard (`Networks → Tunnels → Create`), copies the token, and configures a Public Hostname pointing at `localhost:<port>` (where `<port>` is the in-container upstream).
+- The URL is whatever subdomain on their domain they configured (e.g. `https://agent.example.com`).
+- The URL never rotates. It's bound to the tunnel in the dashboard, not the process.
+- `cloudflared` runs inside the container with `cloudflared tunnel run --token <jwt>`. The token comes from `.env`.
+
+Use `provider: "cloudflare-named"` with `hostname: "https://..."` and `tokenEnv: "CLOUDFLARE_TUNNEL_TOKEN"` (or another env var name set in `.env`). The user must:
+
+1. Create the tunnel in the Cloudflare dashboard.
+2. Add at least one Public Hostname mapping `<sub>.<their-domain>` → `localhost:<port>`. A tunnel without a Public Hostname is a no-op — `cloudflared` registers but has nothing to route.
+3. Put the dashboard-printed token in `.env` under the env var named in `tokenEnv`.
+4. `typeclaw restart` to pick up the new tunnel and the cloudflared layer.
+
+The `hostname` field in `typeclaw.json` is informational — typeclaw uses it for `tunnel-url-changed` events and CLI display, but `cloudflared` reads the actual hostname→upstream mapping from the dashboard. If the user changes the hostname in the dashboard, they must also update `tunnels[].hostname` in `typeclaw.json` or downstream consumers (GitHub webhook registration) will keep using the stale URL.
+
+`upstreamPort` is not used for `cloudflare-named` — the dashboard's Public Hostname mapping captures it. The schema rejects `upstreamPort` on named tunnels to surface drift early.
+
 ### External URL
 
 Choose External when the user already has their own reverse proxy or tunnel:
@@ -90,7 +111,18 @@ Use `typeclaw tunnel logs <name> -f` while restarting the agent if you need to w
 
 ### `cloudflared` is not installed
 
-The Cloudflare Quick provider requires `docker.file.cloudflared: true`. If it is missing, add it to `typeclaw.json` or re-run the GitHub channel setup choosing Cloudflare Quick, then run `typeclaw restart` so the Dockerfile is regenerated and the image rebuilds.
+Both Cloudflare providers (`cloudflare-quick` and `cloudflare-named`) require `docker.file.cloudflared: true`. If it is missing, `typeclaw tunnel add` writes it automatically; otherwise add it to `typeclaw.json` by hand and run `typeclaw restart` so the Dockerfile is regenerated and the image rebuilds.
+
+### Named tunnel says "permanently-failed" with `tokenEnv` in the detail
+
+The env var named in `tunnels[].tokenEnv` is not set or is empty in the agent's `.env`. The provider intentionally does not retry this case — fix `.env`, then `typeclaw restart`. `cloudflared` is never spawned with a missing token.
+
+### Named tunnel is healthy but no traffic flows
+
+Two likely causes:
+
+1. The Cloudflare dashboard's Public Hostname tab for this tunnel is empty. A tunnel with no public hostname is a no-op — `cloudflared` registers and waits, but Cloudflare has nothing to route to it. `curl https://<hostname>` returns Cloudflare error 530 or 1033.
+2. The Public Hostname's upstream `localhost:<port>` does not match the in-container service port. typeclaw cannot detect this drift; the user must align the dashboard and the container.
 
 ### Quick tunnel URL changed