Upload 23 files

.github/FUNDING.yml

@@ -0,0 +1 @@
+custom: ["https://github.com/sponsors/steipete"]

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Report a problem or unexpected behavior in Clawdbot.
+title: "[Bug]: "
+labels: bug
+---
+
+## Summary
+
+What went wrong?
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Expected behavior
+
+What did you expect to happen?
+
+## Actual behavior
+
+What actually happened?
+
+## Environment
+
+- Clawdbot version:
+- OS:
+- Install method (pnpm/npx/docker/etc):
+
+## Logs or screenshots
+
+Paste relevant logs or add screenshots (redact secrets).

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Onboarding
+    url: https://discord.gg/clawd
+    about: New to Clawdbot? Join Discord for setup guidance from Krill in #help.
+  - name: Support
+    url: https://discord.gg/clawd
+    about: Get help from Krill and the community on Discord in #help.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Suggest an idea or improvement for Clawdbot.
+title: "[Feature]: "
+labels: enhancement
+---
+
+## Summary
+
+Describe the problem you are trying to solve or the opportunity you see.
+
+## Proposed solution
+
+What would you like Clawdbot to do?
+
+## Alternatives considered
+
+Any other approaches you have considered?
+
+## Additional context
+
+Links, screenshots, or related issues.

.github/actionlint.yaml

@@ -0,0 +1,17 @@
+# actionlint configuration
+# https://github.com/rhysd/actionlint/blob/main/docs/config.md
+
+self-hosted-runner:
+  labels:
+    # Blacksmith CI runners
+    - blacksmith-4vcpu-ubuntu-2404
+    - blacksmith-4vcpu-windows-2025
+
+# Ignore patterns for known issues
+paths:
+  .github/workflows/**/*.yml:
+    ignore:
+      # Ignore shellcheck warnings (we run shellcheck separately)
+      - "shellcheck reported issue.+"
+      # Ignore intentional if: false for disabled jobs
+      - 'constant expression "false" in condition'

.github/dependabot.yml

@@ -0,0 +1,113 @@
+# Dependabot configuration
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+
+registries:
+  npm-npmjs:
+    type: npm-registry
+    url: https://registry.npmjs.org
+    replaces-base: true
+
+updates:
+  # npm dependencies (root)
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      production:
+        dependency-type: production
+        update-types:
+          - minor
+          - patch
+      development:
+        dependency-type: development
+        update-types:
+          - minor
+          - patch
+    open-pull-requests-limit: 10
+    registries:
+      - npm-npmjs
+
+  # GitHub Actions
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      actions:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch
+    open-pull-requests-limit: 5
+
+  # Swift Package Manager - macOS app
+  - package-ecosystem: swift
+    directory: /apps/macos
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      swift-deps:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch
+    open-pull-requests-limit: 5
+
+  # Swift Package Manager - shared MoltbotKit
+  - package-ecosystem: swift
+    directory: /apps/shared/MoltbotKit
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      swift-deps:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch
+    open-pull-requests-limit: 5
+
+  # Swift Package Manager - Swabble
+  - package-ecosystem: swift
+    directory: /Swabble
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      swift-deps:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch
+    open-pull-requests-limit: 5
+
+  # Gradle - Android app
+  - package-ecosystem: gradle
+    directory: /apps/android
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    groups:
+      android-deps:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch
+    open-pull-requests-limit: 5

.github/labeler.yml

@@ -0,0 +1,222 @@
+"channel: bluebubbles":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/bluebubbles/**"
+          - "docs/channels/bluebubbles.md"
+"channel: discord":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/discord/**"
+          - "extensions/discord/**"
+          - "docs/channels/discord.md"
+"channel: googlechat":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/googlechat/**"
+          - "docs/channels/googlechat.md"
+"channel: imessage":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/imessage/**"
+          - "extensions/imessage/**"
+          - "docs/channels/imessage.md"
+"channel: line":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/line/**"
+          - "docs/channels/line.md"
+"channel: matrix":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/matrix/**"
+          - "docs/channels/matrix.md"
+"channel: mattermost":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/mattermost/**"
+          - "docs/channels/mattermost.md"
+"channel: msteams":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/msteams/**"
+          - "docs/channels/msteams.md"
+"channel: nextcloud-talk":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/nextcloud-talk/**"
+          - "docs/channels/nextcloud-talk.md"
+"channel: nostr":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/nostr/**"
+          - "docs/channels/nostr.md"
+"channel: signal":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/signal/**"
+          - "extensions/signal/**"
+          - "docs/channels/signal.md"
+"channel: slack":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/slack/**"
+          - "extensions/slack/**"
+          - "docs/channels/slack.md"
+"channel: telegram":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/telegram/**"
+          - "extensions/telegram/**"
+          - "docs/channels/telegram.md"
+"channel: tlon":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/tlon/**"
+          - "docs/channels/tlon.md"
+"channel: voice-call":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/voice-call/**"
+"channel: whatsapp-web":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/web/**"
+          - "extensions/whatsapp/**"
+          - "docs/channels/whatsapp.md"
+"channel: zalo":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/zalo/**"
+          - "docs/channels/zalo.md"
+"channel: zalouser":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/zalouser/**"
+          - "docs/channels/zalouser.md"
+
+"app: android":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "apps/android/**"
+          - "docs/platforms/android.md"
+"app: ios":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "apps/ios/**"
+          - "docs/platforms/ios.md"
+"app: macos":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "apps/macos/**"
+          - "docs/platforms/macos.md"
+          - "docs/platforms/mac/**"
+"app: web-ui":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "ui/**"
+          - "src/gateway/control-ui.ts"
+          - "src/gateway/control-ui-shared.ts"
+          - "src/gateway/protocol/**"
+          - "src/gateway/server-methods/chat.ts"
+          - "src/infra/control-ui-assets.ts"
+
+"gateway":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/gateway/**"
+          - "src/daemon/**"
+          - "docs/gateway/**"
+
+"docs":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "docs/**"
+          - "docs.acp.md"
+
+"cli":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/cli/**"
+
+"commands":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/commands/**"
+
+"scripts":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "scripts/**"
+
+"docker":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "Dockerfile"
+          - "Dockerfile.*"
+          - "docker-compose.yml"
+          - "docker-setup.sh"
+          - ".dockerignore"
+          - "scripts/**/*docker*"
+          - "scripts/**/Dockerfile*"
+          - "scripts/sandbox-*.sh"
+          - "src/agents/sandbox*.ts"
+          - "src/commands/sandbox*.ts"
+          - "src/cli/sandbox-cli.ts"
+          - "src/docker-setup.test.ts"
+          - "src/config/**/*sandbox*"
+          - "docs/cli/sandbox.md"
+          - "docs/gateway/sandbox*.md"
+          - "docs/install/docker.md"
+          - "docs/multi-agent-sandbox-tools.md"
+
+"agents":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "src/agents/**"
+
+"security":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "docs/cli/security.md"
+          - "docs/gateway/security.md"
+
+"extensions: copilot-proxy":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/copilot-proxy/**"
+"extensions: diagnostics-otel":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/diagnostics-otel/**"
+"extensions: google-antigravity-auth":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/google-antigravity-auth/**"
+"extensions: google-gemini-cli-auth":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/google-gemini-cli-auth/**"
+"extensions: llm-task":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/llm-task/**"
+"extensions: lobster":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/lobster/**"
+"extensions: memory-core":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/memory-core/**"
+"extensions: memory-lancedb":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/memory-lancedb/**"
+"extensions: open-prose":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/open-prose/**"
+"extensions: qwen-portal-auth":
+  - changed-files:
+      - any-glob-to-any-file:
+          - "extensions/qwen-portal-auth/**"

.github/workflows/auto-response.yml

@@ -0,0 +1,115 @@
+name: Auto response
+
+on:
+  issues:
+    types: [opened, edited, labeled]
+  pull_request_target:
+    types: [labeled]
+
+permissions: {}
+
+jobs:
+  auto-response:
+    permissions:
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+        id: app-token
+        with:
+          app-id: "2729701"
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+      - name: Handle labeled items
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        with:
+          github-token: ${{ steps.app-token.outputs.token }}
+          script: |
+            // Labels prefixed with "r:" are auto-response triggers.
+            const rules = [
+              {
+                label: "r: skill",
+                close: true,
+                message:
+                  "Thanks for the contribution! New skills should be published to [Clawhub](https://clawhub.ai) for everyone to use. We’re keeping the core lean on skills, so I’m closing this out.",
+              },
+              {
+                label: "r: support",
+                close: true,
+                message:
+                  "Please use [our support server](https://discord.gg/clawd) and ask in #help or #users-helping-users to resolve this, or follow the stuck FAQ at https://docs.openclaw.ai/help/faq#im-stuck-whats-the-fastest-way-to-get-unstuck.",
+              },
+              {
+                label: "r: third-party-extension",
+                close: true,
+                message:
+                  "This would be better made as a third-party extension with our SDK that you maintain yourself. Docs: https://docs.openclaw.ai/plugin.",
+              },
+              {
+                label: "r: moltbook",
+                close: true,
+                lock: true,
+                lockReason: "off-topic",
+                message:
+                  "OpenClaw is not affiliated with Moltbook, and issues related to Moltbook should not be submitted here.",
+              },
+            ];
+
+            const issue = context.payload.issue;
+            if (issue) {
+              const title = issue.title ?? "";
+              const body = issue.body ?? "";
+              const haystack = `${title}\n${body}`.toLowerCase();
+              const hasLabel = (issue.labels ?? []).some((label) =>
+                typeof label === "string" ? label === "r: moltbook" : label?.name === "r: moltbook",
+              );
+              if (haystack.includes("moltbook") && !hasLabel) {
+                await github.rest.issues.addLabels({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: issue.number,
+                  labels: ["r: moltbook"],
+                });
+                return;
+              }
+            }
+
+            const labelName = context.payload.label?.name;
+            if (!labelName) {
+              return;
+            }
+
+            const rule = rules.find((item) => item.label === labelName);
+            if (!rule) {
+              return;
+            }
+
+            const issueNumber = context.payload.issue?.number ?? context.payload.pull_request?.number;
+            if (!issueNumber) {
+              return;
+            }
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: issueNumber,
+              body: rule.message,
+            });
+
+            if (rule.close) {
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issueNumber,
+                state: "closed",
+              });
+            }
+
+            if (rule.lock) {
+              await github.rest.issues.lock({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issueNumber,
+                lock_reason: rule.lockReason ?? "resolved",
+              });
+            }

.github/workflows/ci.yml

@@ -0,0 +1,644 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  install-check:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          check-latest: true
+
+      - name: Setup pnpm (corepack retry)
+        run: |
+          set -euo pipefail
+          corepack enable
+          for attempt in 1 2 3; do
+            if corepack prepare pnpm@10.23.0 --activate; then
+              pnpm -v
+              exit 0
+            fi
+            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Runtime versions
+        run: |
+          node -v
+          npm -v
+          pnpm -v
+
+      - name: Capture node path
+        run: echo "NODE_BIN=$(dirname \"$(node -p \"process.execPath\")\")" >> "$GITHUB_ENV"
+
+      - name: Install dependencies (frozen)
+        env:
+          CI: true
+        run: |
+          export PATH="$NODE_BIN:$PATH"
+          which node
+          node -v
+          pnpm -v
+          pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
+
+  checks:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runtime: node
+            task: tsgo
+            command: pnpm tsgo
+          - runtime: node
+            task: lint
+            command: pnpm build && pnpm lint
+          - runtime: node
+            task: test
+            command: pnpm canvas:a2ui:bundle && pnpm test
+          - runtime: node
+            task: protocol
+            command: pnpm protocol:check
+          - runtime: node
+            task: format
+            command: pnpm format
+          - runtime: bun
+            task: test
+            command: pnpm canvas:a2ui:bundle && bunx vitest run
+          - runtime: bun
+            task: build
+            command: bunx tsc -p tsconfig.json --noEmit false
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          check-latest: true
+
+      - name: Setup pnpm (corepack retry)
+        run: |
+          set -euo pipefail
+          corepack enable
+          for attempt in 1 2 3; do
+            if corepack prepare pnpm@10.23.0 --activate; then
+              pnpm -v
+              exit 0
+            fi
+            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Runtime versions
+        run: |
+          node -v
+          npm -v
+          bun -v
+          pnpm -v
+
+      - name: Capture node path
+        run: echo "NODE_BIN=$(dirname \"$(node -p \"process.execPath\")\")" >> "$GITHUB_ENV"
+
+      - name: Install dependencies
+        env:
+          CI: true
+        run: |
+          export PATH="$NODE_BIN:$PATH"
+          which node
+          node -v
+          pnpm -v
+          pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true || pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
+
+      - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
+        run: ${{ matrix.command }}
+
+  secrets:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install detect-secrets
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install detect-secrets==1.5.0
+
+      - name: Detect secrets
+        run: |
+          if ! detect-secrets scan --baseline .secrets.baseline; then
+            echo "::error::Secret scanning failed. See docs/gateway/security.md#secret-scanning-detect-secrets"
+            exit 1
+          fi
+
+  checks-windows:
+    runs-on: blacksmith-4vcpu-windows-2025
+    env:
+      NODE_OPTIONS: --max-old-space-size=4096
+      CLAWDBOT_TEST_WORKERS: 1
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runtime: node
+            task: build & lint
+            command: pnpm build && pnpm lint
+          - runtime: node
+            task: test
+            command: pnpm canvas:a2ui:bundle && pnpm test
+          - runtime: node
+            task: protocol
+            command: pnpm protocol:check
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          check-latest: true
+
+      - name: Setup pnpm (corepack retry)
+        run: |
+          set -euo pipefail
+          corepack enable
+          for attempt in 1 2 3; do
+            if corepack prepare pnpm@10.23.0 --activate; then
+              pnpm -v
+              exit 0
+            fi
+            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Runtime versions
+        run: |
+          node -v
+          npm -v
+          bun -v
+          pnpm -v
+
+      - name: Capture node path
+        run: echo "NODE_BIN=$(dirname \"$(node -p \"process.execPath\")\")" >> "$GITHUB_ENV"
+
+      - name: Install dependencies
+        env:
+          CI: true
+        run: |
+          export PATH="$NODE_BIN:$PATH"
+          which node
+          node -v
+          pnpm -v
+          pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true || pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
+
+      - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
+        run: ${{ matrix.command }}
+
+  checks-macos:
+    if: github.event_name == 'pull_request'
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - task: test
+            command: pnpm test
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          check-latest: true
+
+      - name: Setup pnpm (corepack retry)
+        run: |
+          set -euo pipefail
+          corepack enable
+          for attempt in 1 2 3; do
+            if corepack prepare pnpm@10.23.0 --activate; then
+              pnpm -v
+              exit 0
+            fi
+            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Runtime versions
+        run: |
+          node -v
+          npm -v
+          pnpm -v
+
+      - name: Capture node path
+        run: echo "NODE_BIN=$(dirname \"$(node -p \"process.execPath\")\")" >> "$GITHUB_ENV"
+
+      - name: Install dependencies
+        env:
+          CI: true
+        run: |
+          export PATH="$NODE_BIN:$PATH"
+          which node
+          node -v
+          pnpm -v
+          pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true || pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
+
+      - name: Run ${{ matrix.task }}
+        env:
+          NODE_OPTIONS: --max-old-space-size=4096
+        run: ${{ matrix.command }}
+
+  macos-app:
+    if: github.event_name == 'pull_request'
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - task: lint
+            command: |
+              swiftlint --config .swiftlint.yml
+              swiftformat --lint apps/macos/Sources --config .swiftformat
+          - task: build
+            command: |
+              set -euo pipefail
+              for attempt in 1 2 3; do
+                if swift build --package-path apps/macos --configuration release; then
+                  exit 0
+                fi
+                echo "swift build failed (attempt $attempt/3). Retrying…"
+                sleep $((attempt * 20))
+              done
+              exit 1
+          - task: test
+            command: |
+              set -euo pipefail
+              for attempt in 1 2 3; do
+                if swift test --package-path apps/macos --parallel --enable-code-coverage --show-codecov-path; then
+                  exit 0
+                fi
+                echo "swift test failed (attempt $attempt/3). Retrying…"
+                sleep $((attempt * 20))
+              done
+              exit 1
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Select Xcode 26.1
+        run: |
+          sudo xcode-select -s /Applications/Xcode_26.1.app
+          xcodebuild -version
+
+      - name: Install XcodeGen / SwiftLint / SwiftFormat
+        run: |
+          brew install xcodegen swiftlint swiftformat
+
+      - name: Show toolchain
+        run: |
+          sw_vers
+          xcodebuild -version
+          swift --version
+
+      - name: Run ${{ matrix.task }}
+        run: ${{ matrix.command }}
+  ios:
+    if: false # ignore iOS in CI for now
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Select Xcode 26.1
+        run: |
+          sudo xcode-select -s /Applications/Xcode_26.1.app
+          xcodebuild -version
+
+      - name: Install XcodeGen
+        run: brew install xcodegen
+
+      - name: Install SwiftLint / SwiftFormat
+        run: brew install swiftlint swiftformat
+
+      - name: Show toolchain
+        run: |
+          sw_vers
+          xcodebuild -version
+          swift --version
+
+      - name: Generate iOS project
+        run: |
+          cd apps/ios
+          xcodegen generate
+
+      - name: iOS tests
+        run: |
+          set -euo pipefail
+          RESULT_BUNDLE_PATH="$RUNNER_TEMP/Clawdis-iOS.xcresult"
+          DEST_ID="$(
+            python3 - <<'PY'
+          import json
+          import subprocess
+          import sys
+          import uuid
+
+          def sh(args: list[str]) -> str:
+            return subprocess.check_output(args, text=True).strip()
+
+          # Prefer an already-created iPhone simulator if it exists.
+          devices = json.loads(sh(["xcrun", "simctl", "list", "devices", "-j"]))
+          candidates: list[tuple[str, str]] = []
+          for runtime, devs in (devices.get("devices") or {}).items():
+            for dev in devs or []:
+              if not dev.get("isAvailable"):
+                continue
+              name = str(dev.get("name") or "")
+              udid = str(dev.get("udid") or "")
+              if not udid or not name.startswith("iPhone"):
+                continue
+              candidates.append((name, udid))
+
+          candidates.sort(key=lambda it: (0 if "iPhone 16" in it[0] else 1, it[0]))
+          if candidates:
+            print(candidates[0][1])
+            sys.exit(0)
+
+          # Otherwise, create one from the newest available iOS runtime.
+          runtimes = json.loads(sh(["xcrun", "simctl", "list", "runtimes", "-j"])).get("runtimes") or []
+          ios = [rt for rt in runtimes if rt.get("platform") == "iOS" and rt.get("isAvailable")]
+          if not ios:
+            print("No available iOS runtimes found.", file=sys.stderr)
+            sys.exit(1)
+
+          def version_key(rt: dict) -> tuple[int, ...]:
+            parts: list[int] = []
+            for p in str(rt.get("version") or "0").split("."):
+              try:
+                parts.append(int(p))
+              except ValueError:
+                parts.append(0)
+            return tuple(parts)
+
+          ios.sort(key=version_key, reverse=True)
+          runtime = ios[0]
+          runtime_id = str(runtime.get("identifier") or "")
+          if not runtime_id:
+            print("Missing iOS runtime identifier.", file=sys.stderr)
+            sys.exit(1)
+
+          supported = runtime.get("supportedDeviceTypes") or []
+          iphones = [dt for dt in supported if dt.get("productFamily") == "iPhone"]
+          if not iphones:
+            print("No iPhone device types for iOS runtime.", file=sys.stderr)
+            sys.exit(1)
+
+          iphones.sort(
+            key=lambda dt: (
+              0 if "iPhone 16" in str(dt.get("name") or "") else 1,
+              str(dt.get("name") or ""),
+            )
+          )
+          device_type_id = str(iphones[0].get("identifier") or "")
+          if not device_type_id:
+            print("Missing iPhone device type identifier.", file=sys.stderr)
+            sys.exit(1)
+
+          sim_name = f"CI iPhone {uuid.uuid4().hex[:8]}"
+          udid = sh(["xcrun", "simctl", "create", sim_name, device_type_id, runtime_id])
+          if not udid:
+            print("Failed to create iPhone simulator.", file=sys.stderr)
+            sys.exit(1)
+          print(udid)
+          PY
+          )"
+          echo "Using iOS Simulator id: $DEST_ID"
+          xcodebuild test \
+            -project apps/ios/Clawdis.xcodeproj \
+            -scheme Clawdis \
+            -destination "platform=iOS Simulator,id=$DEST_ID" \
+            -resultBundlePath "$RESULT_BUNDLE_PATH" \
+            -enableCodeCoverage YES
+
+      - name: iOS coverage summary
+        run: |
+          set -euo pipefail
+          RESULT_BUNDLE_PATH="$RUNNER_TEMP/Clawdis-iOS.xcresult"
+          xcrun xccov view --report --only-targets "$RESULT_BUNDLE_PATH"
+
+      - name: iOS coverage gate (43%)
+        run: |
+          set -euo pipefail
+          RESULT_BUNDLE_PATH="$RUNNER_TEMP/Clawdis-iOS.xcresult"
+          RESULT_BUNDLE_PATH="$RESULT_BUNDLE_PATH" python3 - <<'PY'
+          import json
+          import os
+          import subprocess
+          import sys
+
+          target_name = "Clawdis.app"
+          minimum = 0.43
+
+          report = json.loads(
+            subprocess.check_output(
+              ["xcrun", "xccov", "view", "--report", "--json", os.environ["RESULT_BUNDLE_PATH"]],
+              text=True,
+            )
+          )
+
+          target_coverage = None
+          for target in report.get("targets", []):
+            if target.get("name") == target_name:
+              target_coverage = float(target["lineCoverage"])
+              break
+
+          if target_coverage is None:
+            print(f"Could not find coverage for target: {target_name}")
+            sys.exit(1)
+
+          print(f"{target_name} line coverage: {target_coverage * 100:.2f}% (min {minimum * 100:.2f}%)")
+          if target_coverage + 1e-12 < minimum:
+            sys.exit(1)
+          PY
+
+  android:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - task: test
+            command: ./gradlew --no-daemon :app:testDebugUnitTest
+          - task: build
+            command: ./gradlew --no-daemon :app:assembleDebug
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+
+      - name: Setup Android SDK
+        uses: android-actions/setup-android@v3
+        with:
+          accept-android-sdk-licenses: false
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+        with:
+          gradle-version: 8.11.1
+
+      - name: Install Android SDK packages
+        run: |
+          yes | sdkmanager --licenses >/dev/null
+          sdkmanager --install \
+            "platform-tools" \
+            "platforms;android-36" \
+            "build-tools;36.0.0"
+
+      - name: Run Android ${{ matrix.task }}
+        working-directory: apps/android
+        run: ${{ matrix.command }}

.github/workflows/docker-release.yml

@@ -0,0 +1,143 @@
+name: Docker Release
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  # Build amd64 image
+  build-amd64:
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    outputs:
+      image-digest: ${{ steps.build.outputs.digest }}
+      image-metadata: ${{ steps.meta.outputs.json }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{version}},suffix=-amd64
+            type=semver,pattern={{version}},suffix=-arm64
+            type=ref,event=branch,suffix=-amd64
+            type=ref,event=branch,suffix=-arm64
+
+      - name: Build and push amd64 image
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64
+          labels: ${{ steps.meta.outputs.labels }}
+          tags: ${{ steps.meta.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false
+          push: true
+
+  # Build arm64 image
+  build-arm64:
+    runs-on: ubuntu-24.04-arm
+    permissions:
+      packages: write
+      contents: read
+    outputs:
+      image-digest: ${{ steps.build.outputs.digest }}
+      image-metadata: ${{ steps.meta.outputs.json }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{version}},suffix=-amd64
+            type=semver,pattern={{version}},suffix=-arm64
+            type=ref,event=branch,suffix=-amd64
+            type=ref,event=branch,suffix=-arm64
+
+      - name: Build and push arm64 image
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/arm64
+          labels: ${{ steps.meta.outputs.labels }}
+          tags: ${{ steps.meta.outputs.tags }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          provenance: false
+          push: true
+
+  # Create multi-platform manifest
+  create-manifest:
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    needs: [build-amd64, build-arm64]
+    steps:
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata for manifest
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+
+      - name: Create and push manifest
+        run: |
+          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            ${{ needs.build-amd64.outputs.image-digest }} \
+            ${{ needs.build-arm64.outputs.image-digest }}
+        env:
+          DOCKER_METADATA_OUTPUT_JSON: ${{ steps.meta.outputs.json }}

.github/workflows/formal-conformance.yml

@@ -0,0 +1,124 @@
+name: Formal models (informational conformance)
+
+on:
+  pull_request:
+
+jobs:
+  formal_conformance:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Checkout openclaw (PR)
+        uses: actions/checkout@v4
+        with:
+          path: openclaw
+
+      - name: Checkout formal models
+        uses: actions/checkout@v4
+        with:
+          repository: vignesh07/clawdbot-formal-models
+          ref: main
+          path: clawdbot-formal-models
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Regenerate extracted constants from openclaw
+        run: |
+          set -euo pipefail
+          cd clawdbot-formal-models
+          export OPENCLAW_REPO_DIR="${GITHUB_WORKSPACE}/openclaw"
+          node scripts/extract-tool-groups.mjs
+          node scripts/check-tool-group-alias.mjs
+
+      - name: Model check (green suite)
+        run: |
+          set -euo pipefail
+          cd clawdbot-formal-models
+          make \
+            precedence groups elevated nodes-policy \
+            attacker approvals approvals-token nodes-pipeline \
+            gateway-exposure gateway-exposure-v2 gateway-exposure-v2-protected \
+            gateway-auth-conformance gateway-auth-tailscale gateway-auth-proxy \
+            pairing pairing-cap pairing-idempotency pairing-refresh pairing-refresh-race \
+            ingress-gating ingress-idempotency ingress-dedupe-fallback ingress-trace ingress-trace2 \
+            routing-isolation routing-precedence routing-identitylinks routing-identity-transitive routing-identity-symmetry routing-identity-channel-override \
+            routing-thread-parent discord-pluralkit \
+            ingress-retry session-key-stability session-explosion-bound config-normalization \
+            group-alias-check
+
+      - name: Model check (negative suite, expected violations)
+        continue-on-error: true
+        run: |
+          set -euo pipefail
+          cd clawdbot-formal-models
+          make -k \
+            precedence-negative groups-negative elevated-negative nodes-policy-negative \
+            attacker-negative attacker-nodes-negative attacker-nodes-allowlist-negative attacker-nodes-allowlist-negative \
+            approvals-negative approvals-token-negative nodes-pipeline-negative \
+            gateway-exposure-negative gateway-exposure-v2-negative gateway-exposure-v2-protected-negative \
+            gateway-exposure-v2-unsafe-custom gateway-exposure-v2-unsafe-tailnet gateway-exposure-v2-unsafe-auto \
+            gateway-auth-conformance-negative gateway-auth-tailscale-negative gateway-auth-proxy-negative \
+            pairing-negative pairing-cap-negative pairing-idempotency-negative pairing-refresh-negative pairing-refresh-race-negative \
+            ingress-gating-negative ingress-idempotency-negative ingress-dedupe-fallback-negative ingress-trace-negative ingress-trace2-negative \
+            routing-isolation-negative routing-precedence-negative routing-identitylinks-negative routing-identity-transitive-negative routing-identity-symmetry-negative routing-identity-channel-override-negative \
+            routing-thread-parent-negative discord-pluralkit-negative \
+            ingress-retry-negative session-key-stability-negative config-normalization-negative
+
+      - name: Compute drift
+        id: drift
+        run: |
+          set -euo pipefail
+          cd clawdbot-formal-models
+
+          if git diff --quiet; then
+            echo "drift=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "drift=true" >> "$GITHUB_OUTPUT"
+          git diff > "${GITHUB_WORKSPACE}/formal-models-drift.diff"
+
+      - name: Upload drift diff artifact
+        if: steps.drift.outputs.drift == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: formal-models-conformance-drift
+          path: formal-models-drift.diff
+
+      - name: Comment on PR (informational)
+        if: steps.drift.outputs.drift == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const body = [
+              '⚠️ **Formal models conformance drift detected**',
+              '',
+              'The formal models extracted constants (`generated/*`) do not match this openclaw PR.',
+              '',
+              'This check is **informational** (not blocking merges yet).',
+              'See the `formal-models-conformance-drift` artifact for the diff.',
+              '',
+              'If this change is intentional, follow up by updating the formal models repo or regenerating the extracted artifacts there.',
+            ].join('\n');
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.payload.pull_request.number,
+              body,
+            });
+
+      - name: Summary
+        run: |
+          if [ "${{ steps.drift.outputs.drift }}" = "true" ]; then
+            echo "Formal conformance drift detected (informational)."
+          else
+            echo "Formal conformance: no drift."
+          fi

.github/workflows/install-smoke.yml

@@ -0,0 +1,41 @@
+name: Install Smoke
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  install-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout CLI
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm (corepack retry)
+        run: |
+          set -euo pipefail
+          corepack enable
+          for attempt in 1 2 3; do
+            if corepack prepare pnpm@10.23.0 --activate; then
+              pnpm -v
+              exit 0
+            fi
+            echo "corepack prepare failed (attempt $attempt/3). Retrying..."
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Install pnpm deps (minimal)
+        run: pnpm install --ignore-scripts --frozen-lockfile
+
+      - name: Run installer docker tests
+        env:
+          CLAWDBOT_INSTALL_URL: https://openclaw.ai/install.sh
+          CLAWDBOT_INSTALL_CLI_URL: https://openclaw.ai/install-cli.sh
+          CLAWDBOT_NO_ONBOARD: "1"
+          CLAWDBOT_INSTALL_SMOKE_SKIP_CLI: "1"
+          CLAWDBOT_INSTALL_SMOKE_SKIP_NONROOT: ${{ github.event_name == 'pull_request' && '1' || '0' }}
+          CLAWDBOT_INSTALL_SMOKE_SKIP_PREVIOUS: "1"
+        run: pnpm test:install:smoke

.github/workflows/labeler.yml

@@ -0,0 +1,25 @@
+name: Labeler
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+
+permissions: {}
+
+jobs:
+  label:
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+        id: app-token
+        with:
+          app-id: "2729701"
+          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
+      - uses: actions/labeler@8558fd74291d67161a8a78ce36a881fa63b766a9 # v5
+        with:
+          configuration-path: .github/labeler.yml
+          repo-token: ${{ steps.app-token.outputs.token }}
+          sync-labels: true

.github/workflows/workflow-sanity.yml

@@ -0,0 +1,37 @@
+name: Workflow Sanity
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  no-tabs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Fail on tabs in workflow files
+        run: |
+          python - <<'PY'
+          from __future__ import annotations
+
+          import pathlib
+          import sys
+
+          root = pathlib.Path(".github/workflows")
+          bad: list[str] = []
+          for path in sorted(root.rglob("*.yml")):
+            if b"\t" in path.read_bytes():
+              bad.append(str(path))
+
+          for path in sorted(root.rglob("*.yaml")):
+            if b"\t" in path.read_bytes():
+              bad.append(str(path))
+
+          if bad:
+            print("Tabs found in workflow file(s):")
+            for path in bad:
+              print(f"- {path}")
+            sys.exit(1)
+          PY

.pi/extensions/diff.ts

@@ -0,0 +1,195 @@
+/**
+ * Diff Extension
+ *
+ * /diff command shows modified/deleted/new files from git status and opens
+ * the selected file in VS Code's diff view.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { DynamicBorder } from "@mariozechner/pi-coding-agent";
+import {
+  Container,
+  Key,
+  matchesKey,
+  type SelectItem,
+  SelectList,
+  Text,
+} from "@mariozechner/pi-tui";
+
+interface FileInfo {
+  status: string;
+  statusLabel: string;
+  file: string;
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("diff", {
+    description: "Show git changes and open in VS Code diff view",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("No UI available", "error");
+        return;
+      }
+
+      // Get changed files from git status
+      const result = await pi.exec("git", ["status", "--porcelain"], { cwd: ctx.cwd });
+
+      if (result.code !== 0) {
+        ctx.ui.notify(`git status failed: ${result.stderr}`, "error");
+        return;
+      }
+
+      if (!result.stdout || !result.stdout.trim()) {
+        ctx.ui.notify("No changes in working tree", "info");
+        return;
+      }
+
+      // Parse git status output
+      // Format: XY filename (where XY is two-letter status, then space, then filename)
+      const lines = result.stdout.split("\n");
+      const files: FileInfo[] = [];
+
+      for (const line of lines) {
+        if (line.length < 4) {
+          continue;
+        } // Need at least "XY f"
+
+        const status = line.slice(0, 2);
+        const file = line.slice(2).trimStart();
+
+        // Translate status codes to short labels
+        let statusLabel: string;
+        if (status.includes("M")) {
+          statusLabel = "M";
+        } else if (status.includes("A")) {
+          statusLabel = "A";
+        } else if (status.includes("D")) {
+          statusLabel = "D";
+        } else if (status.includes("?")) {
+          statusLabel = "?";
+        } else if (status.includes("R")) {
+          statusLabel = "R";
+        } else if (status.includes("C")) {
+          statusLabel = "C";
+        } else {
+          statusLabel = status.trim() || "~";
+        }
+
+        files.push({ status: statusLabel, statusLabel, file });
+      }
+
+      if (files.length === 0) {
+        ctx.ui.notify("No changes found", "info");
+        return;
+      }
+
+      const openSelected = async (fileInfo: FileInfo): Promise<void> => {
+        try {
+          // Open in VS Code diff view.
+          // For untracked files, git difftool won't work, so fall back to just opening the file.
+          if (fileInfo.status === "?") {
+            await pi.exec("code", ["-g", fileInfo.file], { cwd: ctx.cwd });
+            return;
+          }
+
+          const diffResult = await pi.exec(
+            "git",
+            ["difftool", "-y", "--tool=vscode", fileInfo.file],
+            {
+              cwd: ctx.cwd,
+            },
+          );
+          if (diffResult.code !== 0) {
+            await pi.exec("code", ["-g", fileInfo.file], { cwd: ctx.cwd });
+          }
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          ctx.ui.notify(`Failed to open ${fileInfo.file}: ${message}`, "error");
+        }
+      };
+
+      // Show file picker with SelectList
+      await ctx.ui.custom<void>((tui, theme, _kb, done) => {
+        const container = new Container();
+
+        // Top border
+        container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+        // Title
+        container.addChild(new Text(theme.fg("accent", theme.bold(" Select file to diff")), 0, 0));
+
+        // Build select items with colored status
+        const items: SelectItem[] = files.map((f) => {
+          let statusColor: string;
+          switch (f.status) {
+            case "M":
+              statusColor = theme.fg("warning", f.status);
+              break;
+            case "A":
+              statusColor = theme.fg("success", f.status);
+              break;
+            case "D":
+              statusColor = theme.fg("error", f.status);
+              break;
+            case "?":
+              statusColor = theme.fg("muted", f.status);
+              break;
+            default:
+              statusColor = theme.fg("dim", f.status);
+          }
+          return {
+            value: f,
+            label: `${statusColor} ${f.file}`,
+          };
+        });
+
+        const visibleRows = Math.min(files.length, 15);
+        let currentIndex = 0;
+
+        const selectList = new SelectList(items, visibleRows, {
+          selectedPrefix: (t) => theme.fg("accent", t),
+          selectedText: (t) => t, // Keep existing colors
+          description: (t) => theme.fg("muted", t),
+          scrollInfo: (t) => theme.fg("dim", t),
+          noMatch: (t) => theme.fg("warning", t),
+        });
+        selectList.onSelect = (item) => {
+          void openSelected(item.value as FileInfo);
+        };
+        selectList.onCancel = () => done();
+        selectList.onSelectionChange = (item) => {
+          currentIndex = items.indexOf(item);
+        };
+        container.addChild(selectList);
+
+        // Help text
+        container.addChild(
+          new Text(theme.fg("dim", " ↑↓ navigate • ←→ page • enter open • esc close"), 0, 0),
+        );
+
+        // Bottom border
+        container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+        return {
+          render: (w) => container.render(w),
+          invalidate: () => container.invalidate(),
+          handleInput: (data) => {
+            // Add paging with left/right
+            if (matchesKey(data, Key.left)) {
+              // Page up - clamp to 0
+              currentIndex = Math.max(0, currentIndex - visibleRows);
+              selectList.setSelectedIndex(currentIndex);
+            } else if (matchesKey(data, Key.right)) {
+              // Page down - clamp to last
+              currentIndex = Math.min(items.length - 1, currentIndex + visibleRows);
+              selectList.setSelectedIndex(currentIndex);
+            } else {
+              selectList.handleInput(data);
+            }
+            tui.requestRender();
+          },
+        };
+      });
+    },
+  });
+}

.pi/extensions/files.ts

@@ -0,0 +1,194 @@
+/**
+ * Files Extension
+ *
+ * /files command lists all files the model has read/written/edited in the active session branch,
+ * coalesced by path and sorted newest first. Selecting a file opens it in VS Code.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { DynamicBorder } from "@mariozechner/pi-coding-agent";
+import {
+  Container,
+  Key,
+  matchesKey,
+  type SelectItem,
+  SelectList,
+  Text,
+} from "@mariozechner/pi-tui";
+
+interface FileEntry {
+  path: string;
+  operations: Set<"read" | "write" | "edit">;
+  lastTimestamp: number;
+}
+
+type FileToolName = "read" | "write" | "edit";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("files", {
+    description: "Show files read/written/edited in this session",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("No UI available", "error");
+        return;
+      }
+
+      // Get the current branch (path from leaf to root)
+      const branch = ctx.sessionManager.getBranch();
+
+      // First pass: collect tool calls (id -> {path, name}) from assistant messages
+      const toolCalls = new Map<string, { path: string; name: FileToolName; timestamp: number }>();
+
+      for (const entry of branch) {
+        if (entry.type !== "message") {
+          continue;
+        }
+        const msg = entry.message;
+
+        if (msg.role === "assistant" && Array.isArray(msg.content)) {
+          for (const block of msg.content) {
+            if (block.type === "toolCall") {
+              const name = block.name;
+              if (name === "read" || name === "write" || name === "edit") {
+                const path = block.arguments?.path;
+                if (path && typeof path === "string") {
+                  toolCalls.set(block.id, { path, name, timestamp: msg.timestamp });
+                }
+              }
+            }
+          }
+        }
+      }
+
+      // Second pass: match tool results to get the actual execution timestamp
+      const fileMap = new Map<string, FileEntry>();
+
+      for (const entry of branch) {
+        if (entry.type !== "message") {
+          continue;
+        }
+        const msg = entry.message;
+
+        if (msg.role === "toolResult") {
+          const toolCall = toolCalls.get(msg.toolCallId);
+          if (!toolCall) {
+            continue;
+          }
+
+          const { path, name } = toolCall;
+          const timestamp = msg.timestamp;
+
+          const existing = fileMap.get(path);
+          if (existing) {
+            existing.operations.add(name);
+            if (timestamp > existing.lastTimestamp) {
+              existing.lastTimestamp = timestamp;
+            }
+          } else {
+            fileMap.set(path, {
+              path,
+              operations: new Set([name]),
+              lastTimestamp: timestamp,
+            });
+          }
+        }
+      }
+
+      if (fileMap.size === 0) {
+        ctx.ui.notify("No files read/written/edited in this session", "info");
+        return;
+      }
+
+      // Sort by most recent first
+      const files = Array.from(fileMap.values()).toSorted(
+        (a, b) => b.lastTimestamp - a.lastTimestamp,
+      );
+
+      const openSelected = async (file: FileEntry): Promise<void> => {
+        try {
+          await pi.exec("code", ["-g", file.path], { cwd: ctx.cwd });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          ctx.ui.notify(`Failed to open ${file.path}: ${message}`, "error");
+        }
+      };
+
+      // Show file picker with SelectList
+      await ctx.ui.custom<void>((tui, theme, _kb, done) => {
+        const container = new Container();
+
+        // Top border
+        container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+        // Title
+        container.addChild(new Text(theme.fg("accent", theme.bold(" Select file to open")), 0, 0));
+
+        // Build select items with colored operations
+        const items: SelectItem[] = files.map((f) => {
+          const ops: string[] = [];
+          if (f.operations.has("read")) {
+            ops.push(theme.fg("muted", "R"));
+          }
+          if (f.operations.has("write")) {
+            ops.push(theme.fg("success", "W"));
+          }
+          if (f.operations.has("edit")) {
+            ops.push(theme.fg("warning", "E"));
+          }
+          const opsLabel = ops.join("");
+          return {
+            value: f,
+            label: `${opsLabel} ${f.path}`,
+          };
+        });
+
+        const visibleRows = Math.min(files.length, 15);
+        let currentIndex = 0;
+
+        const selectList = new SelectList(items, visibleRows, {
+          selectedPrefix: (t) => theme.fg("accent", t),
+          selectedText: (t) => t, // Keep existing colors
+          description: (t) => theme.fg("muted", t),
+          scrollInfo: (t) => theme.fg("dim", t),
+          noMatch: (t) => theme.fg("warning", t),
+        });
+        selectList.onSelect = (item) => {
+          void openSelected(item.value as FileEntry);
+        };
+        selectList.onCancel = () => done();
+        selectList.onSelectionChange = (item) => {
+          currentIndex = items.indexOf(item);
+        };
+        container.addChild(selectList);
+
+        // Help text
+        container.addChild(
+          new Text(theme.fg("dim", " ↑↓ navigate • ←→ page • enter open • esc close"), 0, 0),
+        );
+
+        // Bottom border
+        container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+        return {
+          render: (w) => container.render(w),
+          invalidate: () => container.invalidate(),
+          handleInput: (data) => {
+            // Add paging with left/right
+            if (matchesKey(data, Key.left)) {
+              // Page up - clamp to 0
+              currentIndex = Math.max(0, currentIndex - visibleRows);
+              selectList.setSelectedIndex(currentIndex);
+            } else if (matchesKey(data, Key.right)) {
+              // Page down - clamp to last
+              currentIndex = Math.min(items.length - 1, currentIndex + visibleRows);
+              selectList.setSelectedIndex(currentIndex);
+            } else {
+              selectList.handleInput(data);
+            }
+            tui.requestRender();
+          },
+        };
+      });
+    },
+  });
+}

.pi/extensions/prompt-url-widget.ts

@@ -0,0 +1,193 @@
+import {
+  DynamicBorder,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
+import { Container, Text } from "@mariozechner/pi-tui";
+
+const PR_PROMPT_PATTERN = /^\s*You are given one or more GitHub PR URLs:\s*(\S+)/im;
+const ISSUE_PROMPT_PATTERN = /^\s*Analyze GitHub issue\(s\):\s*(\S+)/im;
+
+type PromptMatch = {
+  kind: "pr" | "issue";
+  url: string;
+};
+
+type GhMetadata = {
+  title?: string;
+  author?: {
+    login?: string;
+    name?: string | null;
+  };
+};
+
+function extractPromptMatch(prompt: string): PromptMatch | undefined {
+  const prMatch = prompt.match(PR_PROMPT_PATTERN);
+  if (prMatch?.[1]) {
+    return { kind: "pr", url: prMatch[1].trim() };
+  }
+
+  const issueMatch = prompt.match(ISSUE_PROMPT_PATTERN);
+  if (issueMatch?.[1]) {
+    return { kind: "issue", url: issueMatch[1].trim() };
+  }
+
+  return undefined;
+}
+
+async function fetchGhMetadata(
+  pi: ExtensionAPI,
+  kind: PromptMatch["kind"],
+  url: string,
+): Promise<GhMetadata | undefined> {
+  const args =
+    kind === "pr"
+      ? ["pr", "view", url, "--json", "title,author"]
+      : ["issue", "view", url, "--json", "title,author"];
+
+  try {
+    const result = await pi.exec("gh", args);
+    if (result.code !== 0 || !result.stdout) {
+      return undefined;
+    }
+    return JSON.parse(result.stdout) as GhMetadata;
+  } catch {
+    return undefined;
+  }
+}
+
+function formatAuthor(author?: GhMetadata["author"]): string | undefined {
+  if (!author) {
+    return undefined;
+  }
+  const name = author.name?.trim();
+  const login = author.login?.trim();
+  if (name && login) {
+    return `${name} (@${login})`;
+  }
+  if (login) {
+    return `@${login}`;
+  }
+  if (name) {
+    return name;
+  }
+  return undefined;
+}
+
+export default function promptUrlWidgetExtension(pi: ExtensionAPI) {
+  const setWidget = (
+    ctx: ExtensionContext,
+    match: PromptMatch,
+    title?: string,
+    authorText?: string,
+  ) => {
+    ctx.ui.setWidget("prompt-url", (_tui, thm) => {
+      const titleText = title ? thm.fg("accent", title) : thm.fg("accent", match.url);
+      const authorLine = authorText ? thm.fg("muted", authorText) : undefined;
+      const urlLine = thm.fg("dim", match.url);
+
+      const lines = [titleText];
+      if (authorLine) {
+        lines.push(authorLine);
+      }
+      lines.push(urlLine);
+
+      const container = new Container();
+      container.addChild(new DynamicBorder((s: string) => thm.fg("muted", s)));
+      container.addChild(new Text(lines.join("\n"), 1, 0));
+      return container;
+    });
+  };
+
+  const applySessionName = (ctx: ExtensionContext, match: PromptMatch, title?: string) => {
+    const label = match.kind === "pr" ? "PR" : "Issue";
+    const trimmedTitle = title?.trim();
+    const fallbackName = `${label}: ${match.url}`;
+    const desiredName = trimmedTitle ? `${label}: ${trimmedTitle} (${match.url})` : fallbackName;
+    const currentName = pi.getSessionName()?.trim();
+    if (!currentName) {
+      pi.setSessionName(desiredName);
+      return;
+    }
+    if (currentName === match.url || currentName === fallbackName) {
+      pi.setSessionName(desiredName);
+    }
+  };
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (!ctx.hasUI) {
+      return;
+    }
+    const match = extractPromptMatch(event.prompt);
+    if (!match) {
+      return;
+    }
+
+    setWidget(ctx, match);
+    applySessionName(ctx, match);
+    void fetchGhMetadata(pi, match.kind, match.url).then((meta) => {
+      const title = meta?.title?.trim();
+      const authorText = formatAuthor(meta?.author);
+      setWidget(ctx, match, title, authorText);
+      applySessionName(ctx, match, title);
+    });
+  });
+
+  pi.on("session_switch", async (_event, ctx) => {
+    rebuildFromSession(ctx);
+  });
+
+  const getUserText = (content: string | { type: string; text?: string }[] | undefined): string => {
+    if (!content) {
+      return "";
+    }
+    if (typeof content === "string") {
+      return content;
+    }
+    return (
+      content
+        .filter((block): block is { type: "text"; text: string } => block.type === "text")
+        .map((block) => block.text)
+        .join("\n") ?? ""
+    );
+  };
+
+  const rebuildFromSession = (ctx: ExtensionContext) => {
+    if (!ctx.hasUI) {
+      return;
+    }
+
+    const entries = ctx.sessionManager.getEntries();
+    const lastMatch = [...entries].toReversed().find((entry) => {
+      if (entry.type !== "message" || entry.message.role !== "user") {
+        return false;
+      }
+      const text = getUserText(entry.message.content);
+      return !!extractPromptMatch(text);
+    });
+
+    const content =
+      lastMatch?.type === "message" && lastMatch.message.role === "user"
+        ? lastMatch.message.content
+        : undefined;
+    const text = getUserText(content);
+    const match = text ? extractPromptMatch(text) : undefined;
+    if (!match) {
+      ctx.ui.setWidget("prompt-url", undefined);
+      return;
+    }
+
+    setWidget(ctx, match);
+    applySessionName(ctx, match);
+    void fetchGhMetadata(pi, match.kind, match.url).then((meta) => {
+      const title = meta?.title?.trim();
+      const authorText = formatAuthor(meta?.author);
+      setWidget(ctx, match, title, authorText);
+      applySessionName(ctx, match, title);
+    });
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    rebuildFromSession(ctx);
+  });
+}

.pi/extensions/redraws.ts

@@ -0,0 +1,26 @@
+/**
+ * Redraws Extension
+ *
+ * Exposes /tui to show TUI redraw stats.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("tui", {
+    description: "Show TUI stats",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        return;
+      }
+      let redraws = 0;
+      await ctx.ui.custom<void>((tui, _theme, _keybindings, done) => {
+        redraws = tui.fullRedraws;
+        done(undefined);
+        return new Text("", 0, 0);
+      });
+      ctx.ui.notify(`TUI full redraws: ${redraws}`, "info");
+    },
+  });
+}

.pi/git/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

.pi/prompts/cl.md

@@ -0,0 +1,58 @@
+---
+description: Audit changelog entries before release
+---
+
+Audit changelog entries for all commits since the last release.
+
+## Process
+
+1. **Find the last release tag:**
+
+   ```bash
+   git tag --sort=-version:refname | head -1
+   ```
+
+2. **List all commits since that tag:**
+
+   ```bash
+   git log <tag>..HEAD --oneline
+   ```
+
+3. **Read each package's [Unreleased] section:**
+   - packages/ai/CHANGELOG.md
+   - packages/tui/CHANGELOG.md
+   - packages/coding-agent/CHANGELOG.md
+
+4. **For each commit, check:**
+   - Skip: changelog updates, doc-only changes, release housekeeping
+   - Determine which package(s) the commit affects (use `git show <hash> --stat`)
+   - Verify a changelog entry exists in the affected package(s)
+   - For external contributions (PRs), verify format: `Description ([#N](url) by [@user](url))`
+
+5. **Cross-package duplication rule:**
+   Changes in `ai`, `agent` or `tui` that affect end users should be duplicated to `coding-agent` changelog, since coding-agent is the user-facing package that depends on them.
+
+6. **Add New Features section after changelog fixes:**
+   - Insert a `### New Features` section at the start of `## [Unreleased]` in `packages/coding-agent/CHANGELOG.md`.
+   - Propose the top new features to the user for confirmation before writing them.
+   - Link to relevant docs and sections whenever possible.
+
+7. **Report:**
+   - List commits with missing entries
+   - List entries that need cross-package duplication
+   - Add any missing entries directly
+
+## Changelog Format Reference
+
+Sections (in order):
+
+- `### Breaking Changes` - API changes requiring migration
+- `### Added` - New features
+- `### Changed` - Changes to existing functionality
+- `### Fixed` - Bug fixes
+- `### Removed` - Removed features
+
+Attribution:
+
+- Internal: `Fixed foo ([#123](https://github.com/badlogic/pi-mono/issues/123))`
+- External: `Added bar ([#456](https://github.com/badlogic/pi-mono/pull/456) by [@user](https://github.com/user))`

.pi/prompts/is.md

@@ -0,0 +1,22 @@
+---
+description: Analyze GitHub issues (bugs or feature requests)
+---
+
+Analyze GitHub issue(s): $ARGUMENTS
+
+For each issue:
+
+1. Read the issue in full, including all comments and linked issues/PRs.
+
+2. **For bugs**:
+   - Ignore any root cause analysis in the issue (likely wrong)
+   - Read all related code files in full (no truncation)
+   - Trace the code path and identify the actual root cause
+   - Propose a fix
+
+3. **For feature requests**:
+   - Read all related code files in full (no truncation)
+   - Propose the most concise implementation approach
+   - List affected files and changes needed
+
+Do NOT implement unless explicitly asked. Analyze and propose only.

.pi/prompts/landpr.md

@@ -0,0 +1,105 @@
+---
+description: Land a PR (merge with proper workflow)
+---
+
+Input
+
+- PR: $1 <number|url>
+  - If missing: use the most recent PR mentioned in the conversation.
+  - If ambiguous: ask.
+
+Do (review-only)
+Goal: produce a thorough review and a clear recommendation (READY for /landpr vs NEEDS WORK). Do NOT merge, do NOT push, do NOT make changes in the repo as part of this command.
+
+1. Identify PR meta + context
+
+   ```sh
+   gh pr view <PR> --json number,title,state,isDraft,author,baseRefName,headRefName,headRepository,url,body,labels,assignees,reviewRequests,files,additions,deletions --jq '{number,title,url,state,isDraft,author:.author.login,base:.baseRefName,head:.headRefName,headRepo:.headRepository.nameWithOwner,additions,deletions,files:.files|length}'
+   ```
+
+2. Read the PR description carefully
+   - Summarize the stated goal, scope, and any “why now?” rationale.
+   - Call out any missing context: motivation, alternatives considered, rollout/compat notes, risk.
+
+3. Read the diff thoroughly (prefer full diff)
+
+   ```sh
+   gh pr diff <PR>
+   # If you need more surrounding context for files:
+   gh pr checkout <PR>   # optional; still review-only
+   git show --stat
+   ```
+
+4. Validate the change is needed / valuable
+   - What user/customer/dev pain does this solve?
+   - Is this change the smallest reasonable fix?
+   - Are we introducing complexity for marginal benefit?
+   - Are we changing behavior/contract in a way that needs docs or a release note?
+
+5. Evaluate implementation quality + optimality
+   - Correctness: edge cases, error handling, null/undefined, concurrency, ordering.
+   - Design: is the abstraction/architecture appropriate or over/under-engineered?
+   - Performance: hot paths, allocations, queries, network, N+1s, caching.
+   - Security/privacy: authz/authn, input validation, secrets, logging PII.
+   - Backwards compatibility: public APIs, config, migrations.
+   - Style consistency: formatting, naming, patterns used elsewhere.
+
+6. Tests & verification
+   - Identify what’s covered by tests (unit/integration/e2e).
+   - Are there regression tests for the bug fixed / scenario added?
+   - Missing tests? Call out exact cases that should be added.
+   - If tests are present, do they actually assert the important behavior (not just snapshots / happy path)?
+
+7. Follow-up refactors / cleanup suggestions
+   - Any code that should be simplified before merge?
+   - Any TODOs that should be tickets vs addressed now?
+   - Any deprecations, docs, types, or lint rules we should adjust?
+
+8. Key questions to answer explicitly
+   - Can we fix everything ourselves in a follow-up, or does the contributor need to update this PR?
+   - Any blocking concerns (must-fix before merge)?
+   - Is this PR ready to land, or does it need work?
+
+9. Output (structured)
+   Produce a review with these sections:
+
+A) TL;DR recommendation
+
+- One of: READY FOR /landpr | NEEDS WORK | NEEDS DISCUSSION
+- 1–3 sentence rationale.
+
+B) What changed
+
+- Brief bullet summary of the diff/behavioral changes.
+
+C) What’s good
+
+- Bullets: correctness, simplicity, tests, docs, ergonomics, etc.
+
+D) Concerns / questions (actionable)
+
+- Numbered list.
+- Mark each item as:
+  - BLOCKER (must fix before merge)
+  - IMPORTANT (should fix before merge)
+  - NIT (optional)
+- For each: point to the file/area and propose a concrete fix or alternative.
+
+E) Tests
+
+- What exists.
+- What’s missing (specific scenarios).
+
+F) Follow-ups (optional)
+
+- Non-blocking refactors/tickets to open later.
+
+G) Suggested PR comment (optional)
+
+- Offer: “Want me to draft a PR comment to the author?”
+- If yes, provide a ready-to-paste comment summarizing the above, with clear asks.
+
+Rules / Guardrails
+
+- Review only: do not merge (`gh pr merge`), do not push branches, do not edit code.
+- If you need clarification, ask questions rather than guessing.

.pi/prompts/reviewpr.md

@@ -0,0 +1,105 @@
+---
+description: Review a PR thoroughly without merging
+---
+
+Input
+
+- PR: $1 <number|url>
+  - If missing: use the most recent PR mentioned in the conversation.
+  - If ambiguous: ask.
+
+Do (review-only)
+Goal: produce a thorough review and a clear recommendation (READY for /landpr vs NEEDS WORK). Do NOT merge, do NOT push, do NOT make changes in the repo as part of this command.
+
+1. Identify PR meta + context
+
+   ```sh
+   gh pr view <PR> --json number,title,state,isDraft,author,baseRefName,headRefName,headRepository,url,body,labels,assignees,reviewRequests,files,additions,deletions --jq '{number,title,url,state,isDraft,author:.author.login,base:.baseRefName,head:.headRefName,headRepo:.headRepository.nameWithOwner,additions,deletions,files:.files|length}'
+   ```
+
+2. Read the PR description carefully
+   - Summarize the stated goal, scope, and any "why now?" rationale.
+   - Call out any missing context: motivation, alternatives considered, rollout/compat notes, risk.
+
+3. Read the diff thoroughly (prefer full diff)
+
+   ```sh
+   gh pr diff <PR>
+   # If you need more surrounding context for files:
+   gh pr checkout <PR>   # optional; still review-only
+   git show --stat
+   ```
+
+4. Validate the change is needed / valuable
+   - What user/customer/dev pain does this solve?
+   - Is this change the smallest reasonable fix?
+   - Are we introducing complexity for marginal benefit?
+   - Are we changing behavior/contract in a way that needs docs or a release note?
+
+5. Evaluate implementation quality + optimality
+   - Correctness: edge cases, error handling, null/undefined, concurrency, ordering.
+   - Design: is the abstraction/architecture appropriate or over/under-engineered?
+   - Performance: hot paths, allocations, queries, network, N+1s, caching.
+   - Security/privacy: authz/authn, input validation, secrets, logging PII.
+   - Backwards compatibility: public APIs, config, migrations.
+   - Style consistency: formatting, naming, patterns used elsewhere.
+
+6. Tests & verification
+   - Identify what's covered by tests (unit/integration/e2e).
+   - Are there regression tests for the bug fixed / scenario added?
+   - Missing tests? Call out exact cases that should be added.
+   - If tests are present, do they actually assert the important behavior (not just snapshots / happy path)?
+
+7. Follow-up refactors / cleanup suggestions
+   - Any code that should be simplified before merge?
+   - Any TODOs that should be tickets vs addressed now?
+   - Any deprecations, docs, types, or lint rules we should adjust?
+
+8. Key questions to answer explicitly
+   - Can we fix everything ourselves in a follow-up, or does the contributor need to update this PR?
+   - Any blocking concerns (must-fix before merge)?
+   - Is this PR ready to land, or does it need work?
+
+9. Output (structured)
+   Produce a review with these sections:
+
+A) TL;DR recommendation
+
+- One of: READY FOR /landpr | NEEDS WORK | NEEDS DISCUSSION
+- 1–3 sentence rationale.
+
+B) What changed
+
+- Brief bullet summary of the diff/behavioral changes.
+
+C) What's good
+
+- Bullets: correctness, simplicity, tests, docs, ergonomics, etc.
+
+D) Concerns / questions (actionable)
+
+- Numbered list.
+- Mark each item as:
+  - BLOCKER (must fix before merge)
+  - IMPORTANT (should fix before merge)
+  - NIT (optional)
+- For each: point to the file/area and propose a concrete fix or alternative.
+
+E) Tests
+
+- What exists.
+- What's missing (specific scenarios).
+
+F) Follow-ups (optional)
+
+- Non-blocking refactors/tickets to open later.
+
+G) Suggested PR comment (optional)
+
+- Offer: "Want me to draft a PR comment to the author?"
+- If yes, provide a ready-to-paste comment summarizing the above, with clear asks.
+
+Rules / Guardrails
+
+- Review only: do not merge (`gh pr merge`), do not push branches, do not edit code.
+- If you need clarification, ask questions rather than guessing.