typeclaw 0.10.0 → 0.11.1

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,49 @@ 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 by piping a JSON payload to `gh api --input -`. `comments[]` accepts line-level entries; each one lands on the diff exactly like a human reviewer's inline comment:
+
+   ```sh
+   cat <<'JSON' | gh api -X POST /repos/owner/repo/pulls/<N>/reviews --input -
+   {
+     "event": "COMMENT",
+     "body": "Overall: looks good with a few nits.",
+     "comments": [
+       { "path": "src/foo.ts", "line": 42, "side": "RIGHT", "body": "nit: prefer `const` here." },
+       { "path": "src/bar.ts", "line": 10, "side": "RIGHT", "body": "Consider extracting this branch into a helper." }
+     ]
+   }
+   JSON
+   ```
+
+   **Always use `--input -` with a quoted heredoc (`<<'JSON'`) for review bodies.** Do **not** use `-f body=...` or `-F 'comments[][body]=...'`: those go through shell argument parsing, so backticks (\`) trigger command substitution and have to be backslash-escaped, which leaks the literal `\` into the rendered comment. The quoted heredoc passes the JSON through untouched — backticks, newlines, and `${...}` all survive verbatim. The same applies to any other `gh api` POST whose body contains backticks, embedded newlines, or shell metacharacters.
+
+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.
+- **Only post comments that the author needs to act on.** Do not post praise ("looks good", "nice refactor", "great work"), affirmations of correct code, or restatements of what a line does. If every comment in your review is positive, post a top-level summary via `channel_reply` instead of a review — or skip commenting and just `APPROVE`. Inline comments are for changes, questions, and blockers, not validation.
+- `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
 

package/src/tui/index.ts

@@ -44,6 +44,14 @@ export type TuiOptions = {
   onVersionMismatch?: (info: VersionMismatch) => void
 }
 
+// Outcome of a single `run()` cycle. The CLI's reconnect loop reads this to
+// decide whether to spin again or exit. `lostConnection` is true when the
+// WS closed AFTER the connected handshake without a deliberate /quit or
+// Ctrl+C — exactly the case a self-restart produces, and the only one
+// where a fresh connect can recover the session. Quit / Ctrl+C / pre-
+// handshake errors all resolve with `lostConnection: false`.
+export type TuiRunOutcome = { lostConnection: boolean }
+
 export function createTui({
   url,
   initialPrompt,
@@ -54,7 +62,7 @@ export function createTui({
   expectedVersion,
   onVersionMismatch,
 }: TuiOptions) {
-  async function run(): Promise<void> {
+  async function run(): Promise<TuiRunOutcome> {
     const terminal = createTerminal()
     const tui = new TUI(terminal)
     const displayUrl = redactUrl(url)
@@ -80,6 +88,8 @@ export function createTui({
       exit(1)
       throw err
     })
+
+    let userInitiatedShutdown = false
     const { sessionId, serverVersion } = handshake
     status.setText(colors.dim(`session: ${sessionId}`))
     tui.requestRender()
@@ -196,11 +206,11 @@ export function createTui({
       }
     })
 
-    const closed = new Promise<void>((resolve) => {
+    const closed = new Promise<boolean>((resolve) => {
       client.onClose(() => {
         appendHistory(new Text(colors.dim('disconnected'), 0, 0))
         tui.requestRender()
-        resolve()
+        resolve(!userInitiatedShutdown)
       })
     })
 
@@ -223,6 +233,7 @@ export function createTui({
     })
 
     const shutdown = (code: number) => {
+      userInitiatedShutdown = true
       tui.stop()
       client.close()
       exit(code)
@@ -268,13 +279,14 @@ export function createTui({
       // instead of leaking the command into the agent's chat context.
       if (isQuitCommand(initialPrompt)) {
         shutdown(0)
-        return
+        return { lostConnection: false }
       }
       await send(initialPrompt)
     }
 
-    await closed
+    const lostConnection = await closed
     tui.stop()
+    return { lostConnection }
   }
 
   return { run }

package/src/tunnels/index.ts

@@ -1,4 +1,5 @@
 export { createTunnelManager, type TunnelManager, type TunnelManagerOptions, type TunnelManagerLogger } from './manager'
+export { createCloudflareNamedProvider, type CloudflareNamedProviderOptions } from './providers/cloudflare-named'
 export { createCloudflareQuickProvider, type CloudflareQuickProviderOptions } from './providers/cloudflare-quick'
 export {
   type TunnelConfig,

package/src/tunnels/manager.ts

@@ -1,5 +1,6 @@
 import type { Stream } from '@/stream'
 
+import { createCloudflareNamedProvider } from './providers/cloudflare-named'
 import { createCloudflareQuickProvider } from './providers/cloudflare-quick'
 import { createExternalProvider } from './providers/external'
 import type { TunnelConfig, TunnelProviderHandle, TunnelState, TunnelUrlChangedPayload } from './types'
@@ -15,6 +16,11 @@ export type TunnelManagerOptions = {
   stream: Stream
   resolveChannelUpstreamPort?: (channelName: string) => number | null
   cloudflareQuickBinary?: string
+  cloudflareNamedBinary?: string
+  // Reads an env var by name. Defaults to `process.env[name]` in production.
+  // Parameterized so tests can drive the named-provider token path without
+  // poking global env and so the manager stays a pure function of its inputs.
+  resolveEnv?: (name: string) => string | undefined
   logger?: TunnelManagerLogger
 }
 
@@ -36,6 +42,7 @@ const consoleLogger: TunnelManagerLogger = {
 export function createTunnelManager(options: TunnelManagerOptions): TunnelManager {
   const logger = options.logger ?? consoleLogger
   const handles = new Map<string, TunnelProviderHandle>()
+  const resolveEnv = options.resolveEnv ?? ((name: string) => process.env[name])
 
   for (const config of options.tunnels) {
     const handle = buildProvider(
@@ -43,6 +50,8 @@ export function createTunnelManager(options: TunnelManagerOptions): TunnelManage
       options.resolveChannelUpstreamPort,
       (url) => publishUrlChange(options.stream, config, url, logger),
       options.cloudflareQuickBinary,
+      options.cloudflareNamedBinary,
+      resolveEnv,
     )
     handles.set(config.name, handle)
   }
@@ -92,6 +101,8 @@ function buildProvider(
   resolveChannelUpstreamPort: TunnelManagerOptions['resolveChannelUpstreamPort'],
   onUrlChange: (url: string) => void,
   cloudflareQuickBinary: string | undefined,
+  cloudflareNamedBinary: string | undefined,
+  resolveEnv: (name: string) => string | undefined,
 ): TunnelProviderHandle {
   switch (config.provider) {
     case 'external':
@@ -103,6 +114,13 @@ function buildProvider(
         onUrlChange,
         binary: cloudflareQuickBinary,
       })
+    case 'cloudflare-named':
+      return createCloudflareNamedProvider({
+        config,
+        onUrlChange,
+        resolveToken: () => (config.tokenEnv !== undefined ? resolveEnv(config.tokenEnv) : undefined),
+        binary: cloudflareNamedBinary,
+      })
   }
 }
 

package/src/tunnels/providers/cloudflare-named.ts

@@ -0,0 +1,224 @@
+import type { Unsubscribe } from '@/stream'
+
+import { createLogRing, type LogLineSubscriber, type LogRing } from '../log-ring'
+import type { TunnelConfig, TunnelProviderHandle, TunnelState } from '../types'
+
+const DEFAULT_BINARY = 'cloudflared'
+const DEFAULT_RESTART_BACKOFF_MS = [1_000, 2_000, 4_000, 10_000, 30_000]
+const DEFAULT_MAX_CONSECUTIVE_CRASHES = 10
+const DEFAULT_STOP_GRACE_MS = 5_000
+
+export type CloudflareNamedProviderOptions = {
+  config: TunnelConfig
+  onUrlChange: (url: string) => void
+  // Token resolver. Production wiring reads `process.env[config.tokenEnv]`;
+  // the resolver is parameterized so tests can inject a value without poking
+  // global env. Returning `undefined` (or empty string) at any call fails the
+  // start with a clear error pointing at the env-var name.
+  resolveToken: () => string | undefined
+  binary?: string
+  restartBackoffMs?: number[]
+  maxConsecutiveCrashes?: number
+  stopGraceMs?: number
+}
+
+export type CloudflareNamedProviderHandle = TunnelProviderHandle & {
+  tail: () => string[]
+  subscribeToLogs: (cb: LogLineSubscriber) => Unsubscribe
+}
+
+export function createCloudflareNamedProvider(options: CloudflareNamedProviderOptions): CloudflareNamedProviderHandle {
+  const { config, onUrlChange, resolveToken } = options
+  if (config.provider !== 'cloudflare-named') {
+    throw new Error(`createCloudflareNamedProvider: provider must be 'cloudflare-named', got '${config.provider}'`)
+  }
+  const hostname = config.hostname
+  if (hostname === undefined || hostname.trim() === '') {
+    throw new Error(`tunnel '${config.name}' (cloudflare-named): hostname is required`)
+  }
+  const tokenEnv = config.tokenEnv
+  if (tokenEnv === undefined || tokenEnv.trim() === '') {
+    throw new Error(`tunnel '${config.name}' (cloudflare-named): tokenEnv is required`)
+  }
+
+  const binary = options.binary ?? DEFAULT_BINARY
+  const restartBackoffMs = options.restartBackoffMs ?? DEFAULT_RESTART_BACKOFF_MS
+  const maxConsecutiveCrashes = options.maxConsecutiveCrashes ?? DEFAULT_MAX_CONSECUTIVE_CRASHES
+  const stopGraceMs = options.stopGraceMs ?? DEFAULT_STOP_GRACE_MS
+  const logs = createLogRing()
+  const state: TunnelState = {
+    name: config.name,
+    provider: 'cloudflare-named',
+    for: config.for,
+    url: null,
+    status: 'stopped',
+    lastUrlAt: null,
+    detail: '',
+  }
+
+  let started = false
+  let stopping = false
+  let proc: ReturnType<typeof Bun.spawn> | null = null
+  let retryTimer: ReturnType<typeof setTimeout> | null = null
+  let consecutiveCrashes = 0
+
+  async function launch(): Promise<void> {
+    if (!started || stopping) return
+
+    const token = resolveToken()
+    if (token === undefined || token.trim() === '') {
+      // Bad config rather than a transient process crash: the user-facing fix
+      // is editing `.env`, not waiting for backoff. Flip straight to
+      // permanently-failed so `tunnel status` makes the cause obvious and we
+      // don't waste retries spawning a cloudflared we know will reject the
+      // missing token.
+      state.status = 'permanently-failed'
+      state.detail = `env var ${tokenEnv} is unset or empty; set it in .env and restart`
+      return
+    }
+
+    state.status = 'starting'
+    state.detail = 'starting cloudflared'
+    const spawned = Bun.spawn([binary, 'tunnel', '--no-autoupdate', 'run', '--token', token], {
+      stdout: 'ignore',
+      stderr: 'pipe',
+    })
+    proc = spawned
+
+    // Mark healthy on the FIRST stderr line. cloudflared with a valid token
+    // prints registration progress to stderr within ~1s of start; a process
+    // that exits before printing anything is almost certainly a token/network
+    // failure. Healthy != "traffic flowing" — only Cloudflare's edge knows
+    // that — but it's the strongest signal available locally and matches the
+    // quick provider's "saw something on stderr" health model.
+    //
+    // Deliberately does NOT reset `consecutiveCrashes`. A process that prints
+    // one line of stderr then crashes is a tight crash loop (bad token,
+    // network down, cloudflared bug); the counter must trip the cap. The
+    // counter resets on operator action (`stop()` then `start()` again) or
+    // on `typeclaw restart`, not on stderr noise.
+    let sawFirstLine = false
+    void pumpStderr(spawned.stderr, logs, () => {
+      if (sawFirstLine) return
+      sawFirstLine = true
+      state.status = 'healthy'
+      state.detail = 'cloudflared started'
+    })
+
+    void spawned.exited.then((code) => {
+      if (proc !== spawned) return
+      proc = null
+      if (!started || stopping) return
+      handleExit(code)
+    })
+  }
+
+  function handleExit(code: number): void {
+    consecutiveCrashes += 1
+    if (consecutiveCrashes >= maxConsecutiveCrashes) {
+      state.status = 'permanently-failed'
+      state.detail = `cloudflared exited ${code}; retry cap reached after ${consecutiveCrashes} consecutive crashes`
+      return
+    }
+
+    state.status = 'unhealthy'
+    state.detail = `cloudflared exited ${code}; restarting`
+    const delay = restartBackoffMs[Math.min(consecutiveCrashes - 1, restartBackoffMs.length - 1)] ?? 30_000
+    retryTimer = setTimeout(() => {
+      retryTimer = null
+      void launch()
+    }, delay)
+  }
+
+  return {
+    async start(): Promise<void> {
+      if (started) return
+      started = true
+      stopping = false
+      consecutiveCrashes = 0
+      // The URL is known from config, not from cloudflared. Emit it
+      // synchronously so subscribers (channel adapters, tunnel-bridge) wire
+      // up immediately, regardless of whether cloudflared comes up healthy.
+      // For named tunnels, the URL is bound to the dashboard config — even
+      // if the local process is unhealthy, the hostname is the right value
+      // to surface in `tunnel-url-changed` events.
+      state.url = hostname
+      state.lastUrlAt = Date.now()
+      onUrlChange(hostname)
+      await launch()
+    },
+    async stop(): Promise<void> {
+      if (!started && proc === null) return
+      started = false
+      stopping = true
+      if (retryTimer !== null) {
+        clearTimeout(retryTimer)
+        retryTimer = null
+      }
+
+      const running = proc
+      proc = null
+      if (running !== null) {
+        running.kill('SIGTERM')
+        await Promise.race([
+          running.exited,
+          sleep(stopGraceMs).then(() => {
+            running.kill('SIGKILL')
+            return running.exited
+          }),
+        ])
+      }
+
+      stopping = false
+      state.status = 'stopped'
+      state.detail = ''
+    },
+    snapshot(): TunnelState {
+      return { ...state }
+    },
+    tail(): string[] {
+      return logs.snapshot()
+    },
+    subscribeToLogs(cb: LogLineSubscriber): Unsubscribe {
+      return logs.subscribe(cb)
+    },
+  }
+}
+
+async function pumpStderr(
+  stream: ReadableStream<Uint8Array> | null,
+  logs: LogRing,
+  onLine: (line: string) => void,
+): Promise<void> {
+  if (stream === null) return
+  const reader = stream.getReader()
+  const decoder = new TextDecoder()
+  let buffered = ''
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buffered += decoder.decode(value, { stream: true })
+      let newlineIndex = buffered.indexOf('\n')
+      while (newlineIndex !== -1) {
+        const line = buffered.slice(0, newlineIndex).replace(/\r$/, '')
+        logs.append(line)
+        onLine(line)
+        buffered = buffered.slice(newlineIndex + 1)
+        newlineIndex = buffered.indexOf('\n')
+      }
+    }
+    buffered += decoder.decode()
+    if (buffered !== '') {
+      const line = buffered.replace(/\r$/, '')
+      logs.append(line)
+      onLine(line)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/tunnels/types.ts

@@ -1,6 +1,6 @@
 import type { Unsubscribe } from '@/stream'
 
-export type TunnelProvider = 'external' | 'cloudflare-quick'
+export type TunnelProvider = 'external' | 'cloudflare-quick' | 'cloudflare-named'
 
 export type TunnelFor = { kind: 'channel'; name: string } | { kind: 'manual' }
 
@@ -10,6 +10,22 @@ export type TunnelConfig = {
   for: TunnelFor
   externalUrl?: string
   upstreamPort?: number
+  // cloudflare-named only: the public hostname configured in the Cloudflare
+  // dashboard (e.g. `https://agent.example.com`). typeclaw uses it verbatim
+  // for `tunnel-url-changed` events and CLI display; cloudflared itself
+  // learns the hostname → upstream mapping from the dashboard at runtime, so
+  // the value here must mirror what the user typed in `Public Hostname`. If
+  // the two drift, traffic stops flowing but typeclaw still reports the
+  // stale URL — there is no programmatic way to detect this without hitting
+  // Cloudflare's API, which we deliberately don't do.
+  hostname?: string
+  // cloudflare-named only: name of an env var (set in the agent's `.env`)
+  // that holds the tunnel token printed by the Cloudflare dashboard when the
+  // tunnel was created. The token itself never lives in typeclaw.json — only
+  // the env-var name does. The container reads `process.env[tokenEnv]` at
+  // tunnel start. Missing/empty values fail the start with a clear message
+  // pointing at the env var name.
+  tokenEnv?: string
 }
 
 export type TunnelStatus = 'stopped' | 'starting' | 'healthy' | 'unhealthy' | 'permanently-failed'