thepopebot 1.2.76-beta.36 → 1.2.76-beta.38

package/api/CLAUDE.md

@@ -11,31 +11,35 @@ Most routes require a valid API key passed via the `x-api-key` header. API keys
 Auth flow: `x-api-key` header → `verifyApiKey()` → DB lookup (hashed, timing-safe comparison). Two key types exist:
 
 - **User-owned API keys** — long-lived, created via the admin UI, used by external callers (cURL, GitHub Actions, Telegram register).
-- **Per-job agent API keys** (`agent_job_api_key`) — short-lived, auto-created when an agent-job container launches (`createAgentJobApiKey()` in `lib/db/api-keys.js`), tied to the container name, and cleaned up by the maintenance cron after expiry. Only this key type is allowed to call `/api/get-agent-job-secret` (the route rejects other types).
+- **Per-job agent API keys** (`agent_job_api_key`) — short-lived, auto-created when an agent-job container launches (`createAgentJobApiKey()` in `lib/db/api-keys.js`), tied to the container name, and cleaned up by the maintenance cron after expiry. Routes that read agent-job secrets (`/api/get-agent-job-secret`, `/api/agent-job-list-secrets`) reject any other key type.
 
 ## Do NOT use these routes for browser UI
 
 Browser-facing data fetching uses **fetch route handlers** colocated with pages (`route.js` files in `web/app/`). These check `auth()` session — never use `/api` routes from the browser. Server actions (`'use server'`) are used only for **mutations** (rename, delete, star, config updates) — never for data fetching (causes page refresh issues). Handler implementations live in `lib/chat/api.js`; route files are thin re-exports.
 
+Mutation server actions in `lib/chat/actions.js` use `requireAdmin()` for settings/config writes and `requireAuth()` for chat CRUD on user-owned rows. Reads stay open to any logged-in user. Sidebar items like Upgrade are gated on `user.role === 'admin'`.
+
 | Caller | Mechanism | Auth |
 |--------|-----------|------|
 | External (cURL, GitHub Actions, Telegram) | `/api` route | `x-api-key` header |
 | Browser UI (data fetching) | Fetch route handler colocated with page | `auth()` session |
-| Browser UI (mutations) | Server action | `requireAuth()` session |
-| Browser UI (streaming) | `/stream/chat`, `/stream/containers`, `/stream/cluster/*/logs` | `auth()` session |
+| Browser UI (mutations) | Server action | `requireAuth()` / `requireAdmin()` |
+| Browser UI (streaming) | `/stream/chat`, `/stream/containers`, `/stream/containers/logs`, `/stream/cluster/*/logs` | `auth()` session |
 
 ## Routes
 
 | Method | Path | Auth | Handler |
 |--------|------|------|---------|
 | GET | `/api/ping` | None | Health check |
-| POST | `/api/create-agent-job` | `x-api-key` | Create agent job. Body: `{ agent_job, llm_model?, agent_backend?, scope? }` |
-| GET | `/api/get-agent-job-secret` | `agent_job_api_key` only | Get an agent job secret. `oauth2` credentials return only the access_token (auto-refreshed under a lock; rotated refresh tokens are persisted back). Other secret types return the raw value. |
-| POST | `/api/set-agent-job-secret` | `agent_job_api_key` only | Create or update an agent-job secret from inside the container (used by the `set-secret` skill). |
-| GET | `/api/agent-job-list-secrets` | `x-api-key` | List agent job secret keys (no values); returns `{secrets: [{key, isSet, updatedAt, secretType}]}` |
+| POST | `/api/create-agent-job` | `x-api-key` | Create agent job. Body: `{ agent_job, llm_model?, agent_backend?, scope?, user_id? }`. `user_id` attributes the job to that user — the PR-merge webhook reads it back to DM the originator instead of broadcasting. |
+| GET | `/api/get-agent-job-secret` | `agent_job_api_key` only | Get an agent job secret. `key` query param is upper-cased before lookup (admin form already saves uppercase). `oauth2` credentials return only the access_token (auto-refreshed under a per-key lock; rotated refresh tokens are persisted back). Other secret types return the raw value. |
+| GET | `/api/agent-job-list-secrets` | `agent_job_api_key` only | List agent job secret keys (no values); returns `{secrets: [{key, isSet, updatedAt, secretType}]}` |
 | GET | `/api/agent-jobs/status` | `x-api-key` | Agent job status (query: `?agent_job_id=`) |
+| GET | `/api/users` | `x-api-key` | List users with verified DM channels: `{users: [{id, email, first_name, last_name, nickname, role, channels: ['telegram', ...]}]}`. Used by the `agent-job-dm` skill. |
+| POST | `/api/send-dm` | `x-api-key` | Dispatch a system message. Body: `{ user_id?, message, payload? }`. With `user_id`: write 1 row + push to that user's default channel. Without: fan out 1 row per admin where `subscribedToSystemMessages=1`, each pushed to their default channel. Returns `{ok, recipients}`. |
 | POST | `/api/telegram/webhook` | Telegram webhook secret | Telegram message handler (per-user routing via `user_channels`; verifies via `/verify <code>`, dispatches `/session` commands) |
-| POST | `/api/telegram/register` | `x-api-key` | Register bot token + webhook URL |
-| POST | `/api/github/webhook` | GitHub webhook secret | GitHub event handler |
+| POST | `/api/github/webhook` | GitHub webhook secret | GitHub event handler. PR-merge events read `user_id` from `agent-job.config.json` and dispatch the completion message via `dispatchSystemMessage` (per-user when set; broadcast to subscribed admins when absent). |
 | POST | `/api/cluster/:clusterId/role/:roleId/webhook` | `x-api-key` | Trigger cluster role execution |
 | GET/POST | `/api/oauth/callback` | `state` token | OAuth provider redirect target. Exchanges `code` for tokens, persists via `setAgentJobSecret(name, stored, 'oauth')`. |
+
+Telegram bot configuration (token + webhook registration) is done from the admin UI at `/admin/event-handler/telegram`, not via an API route.

package/api/index.js

@@ -1,6 +1,5 @@
 import { createHash, timingSafeEqual, randomUUID } from 'crypto';
 import { createAgentJob } from '../lib/tools/create-agent-job.js';
-import { setWebhook } from '../lib/tools/telegram.js';
 import { getAgentJobStatus, fetchAgentJobLog } from '../lib/tools/github.js';
 import { getTelegramAdapter } from '../lib/channels/index.js';
 import { dispatchCommand, dispatchPreAuthCommand } from '../lib/channels/commands/index.js';
@@ -17,7 +16,7 @@ import { setAgentJobSecret } from '../lib/db/config.js';
 // ── Per-key lock for OAuth token refresh ────────────────────────────
 const _refreshLocks = new Map();
 
-// Bot token — resolved from DB/env, can be overridden by /telegram/register
+// Bot token — resolved from DB/env
 let telegramBotToken = null;
 
 
@@ -253,23 +252,6 @@ async function handleListAgentSecrets(request) {
   return Response.json({ secrets: listAgentJobSecrets() });
 }
 
-async function handleTelegramRegister(request) {
-  const body = await request.json();
-  const { bot_token, webhook_url } = body;
-  if (!bot_token || !webhook_url) {
-    return Response.json({ error: 'Missing bot_token or webhook_url' }, { status: 400 });
-  }
-
-  try {
-    const result = await setWebhook(bot_token, webhook_url, getConfig('TELEGRAM_WEBHOOK_SECRET'));
-    telegramBotToken = bot_token;
-    return Response.json({ success: true, result });
-  } catch (err) {
-    console.error(err);
-    return Response.json({ error: 'Failed to register webhook' }, { status: 500 });
-  }
-}
-
 async function handleTelegramWebhook(request) {
   const botToken = getTelegramBotToken();
   if (!botToken) return Response.json({ ok: true });
@@ -519,7 +501,6 @@ async function POST(request) {
     case '/create-agent-job':     return handleCreateAgentJob(request);
     case '/send-dm':              return handleSendDm(request);
     case '/telegram/webhook':   return handleTelegramWebhook(request);
-    case '/telegram/register':  return handleTelegramRegister(request);
     case '/github/webhook':     return handleGithubWebhook(request);
     default:                    return Response.json({ error: 'Not found' }, { status: 404 });
   }

package/config/CLAUDE.md

@@ -24,5 +24,6 @@ export { register } from 'thepopebot/instrumentation';
 8. **`startBuiltinCrons()`** — `lib/cron.js`. Starts internal crons (e.g., npm version check). Then warms the in-memory update flag from `lib/db/update-check.js`.
 9. **`startClusterRuntime()`** — `lib/cluster/runtime.js`. Registers cluster role triggers (cron + file watch + webhook).
 10. **`startMaintenanceCron()`** — `lib/maintenance.js`. Hourly cleanup of expired agent-job API keys and other housekeeping.
+11. **Config file watchers** — chokidar watches `agent-job/CRONS.json` and `event-handler/TRIGGERS.json` (with `awaitWriteFinish`). Changes call `reloadCrons()` / `reloadTriggers()` in place — no PM2 restart needed after a `git pull` updates the configs. Invalid JSON is logged and ignored; the previous schedule keeps running.
 
 `initialized` is module-scoped so the sequence runs exactly once even if `register()` is called more than once.

package/lib/CLAUDE.md

@@ -18,10 +18,12 @@ If the task needs to *think*, use `agent`. If it just needs to *do*, use `comman
 
 ## Cron Jobs
 
-Defined in `agent-job/CRONS.json`, loaded by `lib/cron.js` at startup via `node-cron`. Each entry has `name`, `schedule` (cron expression), `type` (`agent`/`command`/`webhook`), and the corresponding action fields (`job`, `command`, or `url`/`method`/`headers`/`vars`). Set `enabled: false` to disable. Agent-type entries support optional `agent_backend`, `llm_model`, and `scope` fields. `agent_backend` picks which coding agent runs the job (e.g. `claude-code`, `codex-cli`); `llm_model` overrides the model within that agent. `scope` sets the agent's working directory to a subdirectory (e.g., `"scope": "agents/gary-vee"`) — the system prompt and skills resolve from that scope.
+Defined in `agent-job/CRONS.json`, loaded by `lib/cron.js` at startup via `node-cron`. Each entry has `name`, `schedule` (cron expression), `type` (`agent`/`command`/`webhook`), and the corresponding action fields (`job`, `command`, or `url`/`method`/`headers`/`vars`). Set `enabled: false` to disable. Agent-type entries support optional `agent_backend`, `llm_model`, `scope`, and `user_id` fields. `agent_backend` picks which coding agent runs the job (e.g. `claude-code`, `codex-cli`); `llm_model` overrides the model within that agent. `scope` sets the agent's working directory to a subdirectory (e.g., `"scope": "agents/gary-vee"`) — the system prompt and skills resolve from that scope. `user_id` attributes the spawned job to a user — its completion DM (after PR merge) routes to that user's inbox; omit to broadcast to subscribed admins.
 
 ## Webhook Triggers
 
-Defined in `event-handler/TRIGGERS.json`, loaded by `lib/triggers.js`. Each trigger watches an endpoint path (`watch_path`) and fires an array of actions (fire-and-forget, after auth, before route handler). Actions use the same `type`/`job`/`command`/`url` fields as cron jobs, including optional `agent_backend`/`llm_model`/`scope` overrides.
+Defined in `event-handler/TRIGGERS.json`, loaded by `lib/triggers.js`. Each trigger watches an endpoint path (`watch_path`) and fires an array of actions (fire-and-forget, after auth, before route handler). Actions use the same `type`/`job`/`command`/`url` fields as cron jobs, including optional `agent_backend`/`llm_model`/`scope`/`user_id` overrides.
+
+Both `lib/cron.js` and `lib/triggers.js` expose `reloadCrons()` / `reloadTriggers()`, called by chokidar watchers in `config/instrumentation.js` when the JSON files change — schedules and trigger maps reload in place without a server restart. Invalid JSON is logged and ignored.
 
 Template tokens in `job` and `command` strings: `{{body}}`, `{{body.field}}`, `{{query}}`, `{{query.field}}`, `{{headers}}`, `{{headers.field}}`.

package/lib/ai/CLAUDE.md

@@ -37,9 +37,12 @@ The "job" sub-mode is no longer wired — a skill will replace autonomous job di
 - `{ type: 'tool-call', toolCallId, toolName, args }`
 - `{ type: 'tool-result', toolCallId, result }`
 - `{ type: 'error', message }` — surfaced to the UI as a red message and persisted for refresh
+- `{ type: 'auto-run', command }` — emitted at stream end when the active mode's `*_AUTO_RUN` flag is on, the workspace has uncommitted changes, and the configured git command (`pull`/`commit`/`push`/`pull-push`/`create-pr`) launched in a workspace command container. `lib/chat/api.js` surfaces it as a `data-auto-run` UI part; the chat page forwards it to WorkspaceBar so the spinner attaches without opening the dialog.
 - `{ type: 'meta', ... }`, `{ type: 'result', ... }` — internal, not emitted to client
 - `{ type: 'thinking-start' | 'thinking' | 'thinking-end' }` — SDK path only
 
+`chatStream()` requires `options.userId` and throws if missing — there are no `'unknown'` / `'telegram'` fallbacks anywhere in chat creation. Both paths set `USER_ID` on the spawned container so skills resolve the originator consistently.
+
 ## Workspace Setup
 
 `ensureWorkspaceRepo()` (workspace-setup.js) is called before either path runs. It clones the repo, sets git identity, and checks out/creates the feature branch on the host — agent-agnostic. The container's `2_clone.sh` is a no-op when `.git` already exists.

package/lib/ai/workspace-setup.js

@@ -15,99 +15,61 @@ async function run(cmd, args, opts) {
 }
 
 /**
- * Ensure workspace directory exists and contains the git repo
- * on the correct branch. Idempotent — safe to call on every message.
+ * Set up the workspace once. If `.git` already exists, returns immediately
+ * and never touches git — git is the source of truth from then on.
  *
- * Replaces Docker entrypoint scripts: setup-git.sh, clone.sh, feature-branch.sh.
+ * First-setup steps: gh auth setup-git, shallow clone the base branch,
+ * set git identity, checkout the feature branch (or stay on base).
  *
  * @param {object} opts
  * @param {string} opts.workspaceDir - Absolute path to workspace directory (the git repo root)
  * @param {string} opts.repo - GitHub owner/repo (e.g. "owner/repo")
  * @param {string} opts.branch - Base branch (e.g. "main")
- * @param {string} [opts.featureBranch] - Feature branch to create/checkout
+ * @param {string} [opts.featureBranch] - Feature branch to create on first setup
  */
 export async function ensureWorkspaceRepo({ workspaceDir, repo, branch, featureBranch }) {
+  // Already set up — never touch git again.
+  if (existsSync(path.join(workspaceDir, '.git'))) return '';
+
+  if (!repo) throw new Error('ensureWorkspaceRepo: repo is required for initial clone');
+  if (!branch) throw new Error(`ensureWorkspaceRepo: branch is required (could not resolve default branch for ${repo})`);
+
   const ghToken = getConfig('GH_TOKEN');
   const env = { ...process.env };
   if (ghToken) env.GH_TOKEN = ghToken;
 
+  mkdirSync(workspaceDir, { recursive: true });
   const execOpts = { cwd: workspaceDir, env };
   const log = [];
 
-  // 1. Create workspace directory
-  mkdirSync(workspaceDir, { recursive: true });
-
-  // 2. Configure git to use GH_TOKEN for GitHub HTTPS URLs (mirrors setup-git.sh)
   if (ghToken) {
     const out = await run('gh', ['auth', 'setup-git'], execOpts);
     if (out) log.push(out);
   }
 
-  // 3. Clone if not already a git repo
-  const hasGit = existsSync(path.join(workspaceDir, '.git'));
-  if (!hasGit) {
-    if (!repo) throw new Error('ensureWorkspaceRepo: repo is required for initial clone');
-    if (!branch) throw new Error(`ensureWorkspaceRepo: branch is required (could not resolve default branch for ${repo})`);
-    const out = await run('git', ['clone', '--branch', branch, `https://github.com/${repo}`, '.'], execOpts);
-    log.push(`Cloned ${repo} (branch: ${branch})`);
-    if (out) log.push(out);
-  }
+  await run('git', ['clone', '--depth', '1', '--branch', branch, `https://github.com/${repo}`, '.'], execOpts);
+  log.push(`Cloned ${repo} (branch: ${branch}, depth 1)`);
 
-  // 3. Git identity (only if not already configured)
-  try {
-    await run('git', ['config', 'user.name'], execOpts);
-  } catch {
-    // Not configured — derive from GitHub token
-    if (ghToken) {
-      try {
-        const userJson = await run('gh', ['api', 'user', '-q', '{name: .name, login: .login, email: .email, id: .id}'], execOpts);
-        const user = JSON.parse(userJson);
-        const name = user.name || user.login;
-        const email = user.email || `${user.id}+${user.login}@users.noreply.github.com`;
-        await run('git', ['config', 'user.name', name], execOpts);
-        await run('git', ['config', 'user.email', email], execOpts);
-        log.push(`Git identity: ${name} <${email}>`);
-      } catch (err) {
-        console.error('[workspace-setup] Failed to set git identity:', err.message);
-      }
-    }
-  }
-
-  // 4. Feature branch checkout
-  if (!featureBranch) return log.join('\n');
-
-  // Already on the right branch locally?
-  try {
-    await run('git', ['rev-parse', '--verify', featureBranch], execOpts);
-    // Branch exists locally — make sure we're on it
-    const current = await run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], execOpts);
-    if (current !== featureBranch) {
-      await run('git', ['checkout', featureBranch], execOpts);
-      log.push(`Checked out ${featureBranch}`);
-    } else {
-      log.push(`Already on ${featureBranch}`);
+  if (ghToken) {
+    try {
+      const userJson = await run('gh', ['api', 'user', '-q', '{name: .name, login: .login, email: .email, id: .id}'], execOpts);
+      const user = JSON.parse(userJson);
+      const name = user.name || user.login;
+      const email = user.email || `${user.id}+${user.login}@users.noreply.github.com`;
+      await run('git', ['config', 'user.name', name], execOpts);
+      await run('git', ['config', 'user.email', email], execOpts);
+      log.push(`Git identity: ${name} <${email}>`);
+    } catch (err) {
+      console.error('[workspace-setup] Failed to set git identity:', err.message);
     }
-    return log.join('\n');
-  } catch {
-    // Branch doesn't exist locally — check remote
   }
 
-  try {
-    const remoteCheck = await run('git', ['ls-remote', '--heads', 'origin', featureBranch], execOpts);
-    if (remoteCheck) {
-      // Remote branch exists — checkout tracking it
-      await run('git', ['checkout', '-B', featureBranch, `origin/${featureBranch}`], execOpts);
-      log.push(`Checked out ${featureBranch} (tracking origin)`);
-    } else {
-      // Create new branch and push
-      await run('git', ['checkout', '-b', featureBranch], execOpts);
-      const pushOut = await run('git', ['push', '-u', 'origin', featureBranch], execOpts);
-      log.push(`Created and pushed ${featureBranch}`);
-      if (pushOut) log.push(pushOut);
-    }
-  } catch (err) {
-    console.error('[workspace-setup] Feature branch error:', err.message);
-    throw err;
+  if (featureBranch && featureBranch !== branch) {
+    await run('git', ['checkout', '-b', featureBranch], execOpts);
+    log.push(`Created and checked out ${featureBranch}`);
+  } else {
+    await run('git', ['checkout', branch], execOpts);
+    log.push(`On ${branch}`);
   }
 
   return log.join('\n');

package/lib/auth/CLAUDE.md

@@ -26,6 +26,19 @@ When `AUTH_SECRET` rotates or the container restarts, old session JWTs can't be
 
 **No implicit login**: After setup, the user is redirected to `/login?created=1` and must authenticate normally. This ensures proper JWT session establishment.
 
+## Role Model + requireAuth / requireAdmin
+
+The `users.role` column defaults to `'user'`. Only `createFirstUser()` writes `'admin'` — every subsequent `addUser()` / `createUser()` row is a regular user unless explicitly promoted via the admin UI. The role lives in the JWT and is surfaced as `session.user.role`.
+
+`lib/auth/index.js` exports two helpers (regular functions, not `'use server'`):
+
+- `requireAuth()` — any logged-in user; throws redirect to `/login` otherwise.
+- `requireAdmin()` — requires `role === 'admin'`; throws redirect to `/forbidden` otherwise.
+
+Mutation server actions in `lib/chat/actions.js` use `requireAdmin()` for settings/config writes (LLM keys, coding-agent config, telegram, voice, webhooks, agent secrets, etc.) and `requireAuth()` for chat/workspace CRUD on user-owned rows. Reads stay open to any logged-in user. The Upgrade sidebar item is gated on `user.role === 'admin'`.
+
+JWT role staleness on demotion is a known limitation — a demoted user keeps `'admin'` in their token until next sign-in.
+
 ## getPageAuthState()
 
 Combines `auth()` + `getUserCount()` in a single `Promise.all()` call. Returns `{ session, needsSetup }`. The login page uses `needsSetup` to show either `<SetupForm>` or `<LoginForm>`.

package/lib/channels/CLAUDE.md

@@ -28,7 +28,7 @@ Abstract interface for platform integrations. Methods:
 
 - **Authorization**: per-user via the `user_channels` table. Unverified chats only accept `/verify <code>`; all other messages are dropped. See `lib/db/user-channels.js` and `lib/channels/commands/verify.js`.
 - **Webhook auth**: Validates `x-telegram-bot-api-secret-token` header against `TELEGRAM_WEBHOOK_SECRET`.
-- **Streaming**: `supportsStreaming` returns `false` — text + tool calls accumulate during streaming and are sent as complete messages once the turn ends. Progressive tool-call rendering (commit 740c734 / d9bf19a) inserts intermediate "→ used X" lines as tool calls land.
+- **Streaming**: `supportsStreaming` returns `false` — text + tool calls accumulate during streaming and are sent as complete messages once the turn ends. Progressive tool-call rendering inserts intermediate "→ used X" lines as tool calls land.
 
 ## Slash Commands (`lib/channels/commands/`)
 

package/lib/chat/CLAUDE.md

@@ -22,17 +22,19 @@ export { getRepositoriesHandler as GET } from 'thepopebot/chat/api';
 - `POST /stream/chat` — AI SDK streaming via `createUIMessageStream`. Handles file attachments (images/PDFs as visual, text files inlined), workspace context, and code mode settings.
 
 **Data fetch routes** (colocated with pages):
-- `/code/repositories`, `/code/branches`, `/code/default-repo` — GitHub repo/branch listing
+- `/code/repositories` (GET), `/code/repositories/create` (POST) — list / create GitHub repos
+- `/code/branches`, `/code/default-branch`, `/code/default-repo` — GitHub branch listing + defaults
 - `/code/workspace-branch` (POST) — update workspace branch
 - `/code/workspace-diff/[workspaceId]` — diff stats
 - `/code/workspace-diff/[workspaceId]/full` — full unified diff
-- `/chats` — chat list with workspace join
-- `/chats/counts` — notification + PR badge counts
+- `/chats/list` — chat list with workspace join
+- `/chats/counts` — sidebar badge counts (`messages`, `pull_requests`, etc.) — `messages` is per-user unread count from the `messages` table
 - `/chat/[chatId]/data` — chat + workspace data
 - `/chat/[chatId]/messages` — chat message history
-- `/code/[workspaceId]/chat-data` — chat data by workspace
+- `/code/[codeWorkspaceId]/chat-data` — chat data + chatMode by workspace (used by terminal-view + code-mode-toggle to pick per-mode storage keys)
 - `/chat/voice-token` — AssemblyAI temporary token
-- `/admin/app-version` — version + update check
+- `/chat/scopes` — list of available agent scopes
+- `/admin/app-version` (GET/POST) — current version + update check
 - `/chat/finalize-chat` (POST) — auto-title after first message
 
 ## Chat Streaming Flow
@@ -40,14 +42,16 @@ export { getRepositoriesHandler as GET } from 'thepopebot/chat/api';
 1. Client sends message via AI SDK `DefaultChatTransport` → `POST /stream/chat`
 2. Handler validates session, extracts text + file attachments from message parts. Images and PDFs pass through as vision content; text files are inlined into the prompt.
 3. Calls `chatStream()` from `lib/ai/` which handles DB persistence and LLM invocation. Two paths: SDK adapter (in-process, e.g. Claude Agent SDK) or direct headless container (other agents).
-4. Streams response chunks (text deltas, tool calls, tool results, thinking blocks) via `createUIMessageStream`. Tool call/tool result pairs and `{ type: 'error' }` chunks are persisted as JSON message parts.
-5. After the first user message streams, the client calls `/chat/finalize-chat` to generate the auto-title (helper LLM with truncated-description fallback).
+4. Streams response chunks (text deltas, tool calls, tool results, thinking blocks, errors) via `createUIMessageStream`. Tool call/tool result pairs and `{ type: 'error' }` chunks are persisted as JSON message parts.
+5. After the stream ends successfully, if the active mode's `*_AUTO_RUN` flag is on and the workspace has uncommitted changes, `chatStream()` launches the configured workspace command (`pull`/`commit`/`push`/`pull-push`/`create-pr`) in a fresh container and yields a final `{ type: 'auto-run', command }` chunk. `api.js` writes it as a `data-auto-run` part; `chat.jsx` forwards it to WorkspaceBar so the spinner attaches.
+6. After the first user message streams, the client calls `/chat/finalize-chat` to generate the auto-title (helper LLM with truncated-description fallback).
 
 ## Server Actions (actions.js)
 
-Used for mutations that don't need streaming responses. Key groups:
+Used for mutations that don't need streaming responses. Settings/config writes go through `requireAdmin()`; chat/workspace CRUD uses `requireAuth()` plus user-id ownership checks. Key groups:
 
 - **Chat CRUD**: `renameChat()`, `deleteChat()`, `starChat()`
 - **Coding agents**: `getCodingAgentSettings()`, `updateCodingAgentConfig()`, `setCodingAgentDefault()`
+- **Mode defaults**: `getModeBranchDefault()`, `getModeGitActionDefault()`, `setModeDefault()` — branch/git-action/auto-run defaults per chat mode (agent vs code). `setModeDefault()` validates against `GIT_COMMAND_SET` from `lib/git-commands.js`.
 - **Agent job secrets**: `getAgentJobSecrets()`, `updateAgentJobSecret()`, `deleteAgentJobSecretAction()`
 - **Container management**: `getRunnersStatus()`, `stopDockerContainer()`, `startDockerContainer()`, `removeDockerContainer()`

package/lib/chat/components/CLAUDE.md

@@ -4,26 +4,29 @@ JSX components for the chat UI. Compiled to `.js` by `npm run build` (esbuild).
 
 ## Admin Navigation
 
-Admin pages live under `/admin/` with two top-level sections:
-
-- **`/admin/event-handler/`** — Event handler config with pill-style sub-tabs via `SubTabLayout` (`settings-secrets-layout.jsx`):
-  - `/admin/event-handler/llms` — LLM provider credentials
-  - `/admin/event-handler/coding-agents` — Multi-agent config (5 backends)
-  - `/admin/event-handler/helper-llm` — Helper LLM settings (provider/model used for chat titles, agent-job titles + summaries)
-  - `/admin/event-handler/jobs` — Agent job custom secrets
-  - `/admin/event-handler/telegram` — Telegram integration
-  - `/admin/event-handler/voice` — Voice input (AssemblyAI)
-  - `/admin/event-handler/webhooks` — Webhook secret
-- **Other admin pages**: `/admin/api-keys`, `/admin/github`, `/admin/users`, `/admin/crons`, `/admin/triggers`, `/admin/general`
+Top-level admin tabs (`settings-layout.jsx`), in order: **General → Event Handler → Crons → Triggers → Users → GitHub**. Most-used settings up front; GitHub (rarely touched once configured) is last.
+
+Sub-tabs under `/admin/event-handler/` (pill-style nav via `SubTabLayout` in `settings-secrets-layout.jsx`):
+- `/admin/event-handler/coding-agents` — Multi-agent config (default coding agent + per-agent enable/auth/provider/model). Section heading: "Coding Agent"; the dropdown row label is "Default Coding Agent".
+- `/admin/event-handler/helper-llm` — Helper LLM (provider/model used for chat titles, agent-job titles + summaries)
+- `/admin/event-handler/llms` — LLM provider credentials + custom OpenAI-compatible providers
+- `/admin/event-handler/agent-secrets` — Custom env vars/secrets injected into agent containers (not `/jobs` — that path is gone)
+- `/admin/event-handler/telegram` — Bot token + webhook register
+- `/admin/event-handler/voice` — Voice input (AssemblyAI)
+- `/admin/event-handler/webhooks` — Webhook secret
+
+The **Clusters** sidebar entry is hidden behind `{false && ...}` for now — markup intact for fast re-enable.
 
 ## Key Component Pages
 
 | Component | File | Purpose |
 |-----------|------|---------|
-| `CodingAgentsPage` | `settings-coding-agents-page.jsx` | Multi-agent config — 5 agent cards with enable/disable, auth mode, model selection |
-| `JobsPage` | `settings-jobs-page.jsx` | Custom env vars for agent job containers |
-| `ContainersPage` | `containers-page.jsx` | Live Docker container monitoring via SSE (`/stream/containers`) |
+| `CodingAgentsPage` | `settings-coding-agents-page.jsx` | Multi-agent config — 6 agent cards (claude-code, pi, codex-cli, gemini-cli, opencode, kimi-cli) with enable/disable, auth mode, model selection. Also holds Default Coding Agent + per-mode Branch/Git action/Auto-run defaults. |
+| `JobsPage` / `JobSecretsManager` | `settings-jobs-page.jsx` | Custom env vars for agent job containers. `JobSecretsManager` is also reused as a popup from the agent-mode chat input (KeyIcon left of the Plan/Code dropdown) via `Dialog` with `maxWidth="max-w-2xl"` and `showHeader={false}`. |
+| `MessagesPage` | `messages-page.jsx` | Per-user inbox (Inbox/All tabs, click-to-mark-read, bulk mark-all, no delete). Replaces the old global `notifications-page.jsx`. |
+| `ContainersPage` | `containers-page.jsx` | Live Docker container monitoring via SSE (`/stream/containers`) plus a per-row logs button (FileTextIcon) that opens `/stream/containers/logs?name=...` |
 | `ChatsPage` | `chats-page.jsx` | Full chat history with search, bulk actions |
+| `ProfilePage` | `profile-page.jsx` | Two forms: **Profile** (firstName/lastName/nickname, no password gate) and **Login & security** (email/password, current password required) |
 
 ## Tool Display Names
 

package/lib/chat/components/code-mode-toggle.js

@@ -192,8 +192,23 @@ function WorkspaceBar({
 }) {
   const [branches, setBranches] = useState([]);
   const [loadingBranches, setLoadingBranches] = useState(false);
+  const branchesLoadedRef = useRef(false);
   const featureBranch = workspace?.featureBranch;
   const repoName = repo ? repo.split("/").pop() : "";
+  const branchOptions = (() => {
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    const push = (name) => {
+      if (!name || seen.has(name)) return;
+      seen.add(name);
+      out.push({ value: name, label: name });
+    };
+    push(branch);
+    const defaultBranch = branches.find((b) => b.isDefault)?.name;
+    push(defaultBranch);
+    for (const b of branches) push(b.name);
+    return out;
+  })();
   return /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2 text-xs min-w-0 px-1 py-0.5", children: [
     /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-1.5 text-muted-foreground min-w-0", children: [
       /* @__PURE__ */ jsx(GitBranchIcon, { size: 12, className: "shrink-0" }),
@@ -203,16 +218,17 @@ function WorkspaceBar({
         /* @__PURE__ */ jsx("div", { className: "min-w-0", children: /* @__PURE__ */ jsx(
           Combobox,
           {
-            options: branches.map((b) => ({ value: b.name, label: b.name })),
+            options: branchOptions,
             value: branch,
             onChange: onBranchChange,
             loading: loadingBranches,
             side: "top",
             onOpen: () => {
-              if (!loadingBranches && repo) {
+              if (!loadingBranches && repo && !branchesLoadedRef.current) {
                 setLoadingBranches(true);
                 getBranches(repo).then((data) => {
                   setBranches(data || []);
+                  branchesLoadedRef.current = true;
                 }).catch(() => {
                   setBranches([]);
                 }).finally(() => setLoadingBranches(false));

package/lib/chat/components/code-mode-toggle.jsx

@@ -208,10 +208,29 @@ export function WorkspaceBar({
 }) {
   const [branches, setBranches] = useState([]);
   const [loadingBranches, setLoadingBranches] = useState(false);
+  const branchesLoadedRef = useRef(false);
 
   const featureBranch = workspace?.featureBranch;
   const repoName = repo ? repo.split('/').pop() : '';
 
+  // Pin the current branch and the repo's default branch to the top of the
+  // dropdown so the user can always re-select them, even if the API list
+  // omits them (very large repos hit pagination caps; deleted branches; etc.).
+  const branchOptions = (() => {
+    const seen = new Set();
+    const out = [];
+    const push = (name) => {
+      if (!name || seen.has(name)) return;
+      seen.add(name);
+      out.push({ value: name, label: name });
+    };
+    push(branch);
+    const defaultBranch = branches.find((b) => b.isDefault)?.name;
+    push(defaultBranch);
+    for (const b of branches) push(b.name);
+    return out;
+  })();
+
   return (
     <div className="flex items-center gap-2 text-xs min-w-0 px-1 py-0.5">
       <div className="flex items-center gap-1.5 text-muted-foreground min-w-0">
@@ -222,16 +241,17 @@ export function WorkspaceBar({
             <span className="shrink-0 text-muted-foreground/30 hidden md:inline">/</span>
             <div className="min-w-0">
               <Combobox
-                options={branches.map((b) => ({ value: b.name, label: b.name }))}
+                options={branchOptions}
                 value={branch}
                 onChange={onBranchChange}
                 loading={loadingBranches}
                 side="top"
                 onOpen={() => {
-                  if (!loadingBranches && repo) {
+                  if (!loadingBranches && repo && !branchesLoadedRef.current) {
                     setLoadingBranches(true);
                     getBranches(repo).then((data) => {
                       setBranches(data || []);
+                      branchesLoadedRef.current = true;
                     }).catch(() => {
                       setBranches([]);
                     }).finally(() => setLoadingBranches(false));

package/lib/code/CLAUDE.md

@@ -25,7 +25,7 @@ All actions use `requireAuth()` with ownership checks: `getCodeWorkspaces()`, `c
 
 ## Multi-Agent Backends
 
-Code workspaces support multiple coding agent backends. Selection is **per-workspace** via the `codingAgent` column on `code_workspaces`, falling back to the global `CODING_AGENT` config key, then to `claude-code`. See `lib/code/actions.js:410`: `const agent = workspace.codingAgent || getConfig('CODING_AGENT') || 'claude-code';`. The same fallback chain is used by `lib/ai/index.js` for chat-mode streaming.
+Code workspaces support multiple coding agent backends. Selection is **per-workspace** via the `codingAgent` column on `code_workspaces`, falling back to the global `CODING_AGENT` config key, then to `claude-code`. The same fallback chain is used by `lib/ai/index.js` for chat-mode streaming.
 
 **Supported agents**: `claude-code`, `pi-coding-agent`, `gemini-cli`, `codex-cli`, `opencode`, `kimi-cli`. Each uses a different Docker image variant (`docker/coding-agent/Dockerfile.*`) and agent-specific setup/auth scripts in `docker/coding-agent/scripts/`.
 
@@ -33,10 +33,20 @@ Code workspaces support multiple coding agent backends. Selection is **per-works
 
 **Container streaming**: `lib/containers/stream.js` provides an SSE endpoint (`/stream/containers`) that polls Docker for container stats every 3 seconds. Used by the Containers admin page for live monitoring.
 
+**USER_ID env**: Interactive containers receive `USER_ID` (originator user id) so skills like `agent-job-dm` and `agent-job-background` resolve attribution without explicit flags.
+
 **Backend API in messages**: When an agent produces output, the `backendApi` field in message chunks identifies which agent backend generated the response.
 
+## Workspace Commands & Auto-Run
+
+`launchWorkspaceCommand(id, command)` and `runWorkspaceCommand(id, command)` (deprecated) spin up an ephemeral `command/<cmd>` runtime container against the workspace volume. Supported commands: `commit`, `push`, `create-pr`, `pull`, `pull-push`. Prompts are sourced from `lib/git-commands.js` (`getCommandPrompt`) — single source of truth shared with the chat dropdown, the workspace toolbar dropup, the admin defaults select, and `maybeAutoRun()` in `lib/ai/index.js`.
+
+Per-run container names are uniquely suffixed (`command-<cmd>-<shortId>-<rand8>`) so repeated invocations don't collide. The matching SSE log endpoint (`/stream/containers/logs?name=...&cleanup=true`) removes the container on every terminal path.
+
+The interactive workspace toolbar's git command button (`terminal-view.jsx`) reads the workspace's `chatMode` from `/code/{id}/chat-data` and uses a per-mode `localStorage` key (`thepopebot-workspace-command:agent` / `:code`) plus a per-mode `FALLBACK_BY_MODE` (`agent`→`pull-push`, `code`→`create-pr`) so agent-mode workspaces don't inherit code-mode defaults.
+
 ## Session Continuity
 
-Code workspaces, chat-mode (SDK adapter), and headless agent jobs share session continuity through `lib/ai/session-manager.js`. Session IDs are written to per-port files inside the workspace volume — `~/.{agent}-ttyd-sessions/${PORT}` (or scope-prefixed when `SCOPE` is set). The agent CLI captures its session ID via per-agent hooks (see `docker/coding-agent/CLAUDE.md` § Session Tracking for the 5 patterns). On the next launch the entrypoint reads the saved ID and passes the agent's resume flag (`--continue`, `--resume`, `--session`, depending on agent).
+Code workspaces, chat-mode (SDK adapter), and headless agent jobs share session continuity through `lib/ai/session-manager.js`. Session IDs are written to per-port files inside the workspace volume — `~/.{agent}-ttyd-sessions/${PORT}` (or scope-prefixed when `SCOPE` is set). The agent CLI captures its session ID via per-agent hooks (see `docker/coding-agent/CLAUDE.md` § Session Tracking for the 5 patterns). Capture is gated on `CONTINUE_SESSION=1` so one-shot command containers (commit/push/create-pr/pull/pull-push) sharing a workspace with a live chat don't overwrite the chat's session file. On the next launch the entrypoint reads the saved ID and passes the agent's resume flag (`--continue`, `--resume`, `--session`, depending on agent).
 
 Headless `run.sh` always reads from port `7681` — so SDK chat, manual chat tools, and code workspaces all converge on the same conversation when they share a workspace.

package/lib/containers/CLAUDE.md

@@ -11,9 +11,10 @@ Two SSE endpoints — both authenticated via `auth()` session.
 
 ## `logs.js` — Container Log Tail
 
-- **Endpoint**: `/stream/containers/logs?name=<containerName>`
+- **Endpoint**: `/stream/containers/logs?name=<containerName>&cleanup=<bool>`
 - **Events**: raw log lines as SSE `data:` frames
 - **Data source**: Docker `containers/{id}/logs?follow=true&stdout=1&stderr=1` via the multiplexed-stream parser in `lib/tools/docker.js`
-- **Client**: `ContainerLogsView` (used from the Containers admin page when a row's logs are expanded)
+- **Client**: `ContainerLogsView` (used from the Containers admin page when a row's logs are expanded). Workspace command containers connect with `cleanup=true`.
+- **`cleanup=true`**: the endpoint removes the container on every terminal path (stream error, tail-setup error, post-exit success, post-exit error). This is required for the per-run unique-named workspace command containers (`command-<cmd>-<shortId>-<rand8>`) to avoid host accumulation.
 
 Both endpoints share the same network filter and frame-decoding logic so all SSE consumers see the same view.

package/lib/db/CLAUDE.md

@@ -22,16 +22,27 @@ Key files: `schema.js` (source of truth), `drizzle/` (generated migrations), `dr
 
 | Table | Purpose |
 |-------|---------|
-| `users` | Admin accounts (email, bcrypt password hash, role) |
+| `users` | User accounts (email, bcrypt password hash, role, first_name/last_name/nickname, subscribed_to_system_messages). `role` defaults to `'user'`; only `createFirstUser()` writes `'admin'`. |
 | `chats` | Chat sessions (user_id, title, starred, chat_mode, code_workspace_id, timestamps) |
-| `messages` | Chat messages (chat_id, role, content) |
+| `messages` | Unified per-user inbox + chat history. `chat_id` nullable (system DMs have none); `user_id` NOT NULL; `payload`, `read`, `delivered_at` columns. Index `messages_inbox_lookup` on `(user_id, read, created_at)` drives the inbox query. |
 | `code_workspaces` | Code workspace containers (user_id, container_name, repo, branch, feature_branch, title, last_interactive_commit, coding_agent, scope, starred, has_changes) |
-| `notifications` | Job completion notifications (notification text, payload, read status) |
-| `subscriptions` | Channel subscriptions (platform, channel_id) |
-| `user_channels` | Per-user channel linking (user_id, channel, channel_chat_id, code, code_expires_at, verified_at, active_thread_id) — Telegram verification + active thread |
+| `user_channels` | Per-user channel linking (user_id, channel, channel_chat_id, code, code_expires_at, verified_at, active_thread_id) — Telegram verification + active thread. `getVerifiedChannels()` orders by `verified_at ASC`; the first verified row is the user's default channel. |
 | `clusters` | Worker clusters (user_id, name, system_prompt, folders, enabled, starred) |
 | `cluster_roles` | Role definitions scoped to a cluster (cluster_id, role_name, role, trigger_config, max_concurrency, plan_mode, cleanup_worker_dir, folders) |
-| `settings` | Key-value configuration store (also stores API keys and OAuth tokens via type/key/value) |
+| `settings` | Key-value configuration store (also stores API keys, OAuth tokens, custom LLM providers, and agent job secrets via type/key/value) |
+
+The legacy `notifications` and `subscriptions` tables were dropped in migration 0025. System DMs (job completion, etc.) are now rows in the `messages` table with `chat_id = NULL`.
+
+## System Messages (`lib/db/messages.js`)
+
+Per-user inbox API:
+
+- `createSystemMessage(userId, content, payload)` — write a row with `chat_id = NULL`, `read = 0`, returns the row.
+- `getSubscribedAdminIds()` — admin user_ids where `subscribed_to_system_messages = 1`. Used for broadcast fan-out when no `user_id` is supplied to `/api/send-dm` or the GitHub PR-merge webhook.
+- `markDelivered(id)` — stamp `delivered_at` after the channel push lands.
+- `getMessagesForUser(userId, {scope})`, `getUnreadCountForUser(userId)`, `markMessageRead(userId, id)`, `markAllReadForUser(userId)` — UI inbox helpers.
+
+`saveMessage(chatId, userId, role, content)` in `lib/db/chats.js` is the chat-history writer; it requires `userId` and logs+throws on missing rows.
 
 ## OAuth Token Storage
 

package/lib/tools/CLAUDE.md

@@ -25,11 +25,15 @@ OAuth tokens use LRU rotation via `getNextOAuthToken()` (in `lib/db/oauth-tokens
 
 ## create-agent-job.js — Agent Job Creation
 
-**Structured output for titles**: Uses `model.withStructuredOutput(z.object({ title }))` to force JSON output and avoid thinking-token leaks with extended-thinking models. Two-tier fallback: LLM → truncated description → first non-empty line with markdown heading syntax stripped.
+**Signature**: `createAgentJob(description, { llmModel?, agentBackend?, scope?, userId? })`. All optional fields land in `agent-job.config.json` as `llm_model` / `agent_backend` / `scope` / `user_id`. `runAgentJobContainer()` reads them back at launch time and threads them into env vars.
+
+**Structured output for titles**: Uses `callHelperLlmStructured({schema: z.object({title})})` to force JSON output and avoid thinking-token leaks with extended-thinking models. Two-tier fallback: LLM → truncated description → first non-empty line with markdown heading syntax stripped.
+
+**Scope SYSTEM.md pre-render**: When `scope` is set, `createAgentJob` itself resolves the scope's `SYSTEM.md` via `buildCodingAgentSystemPrompt()` (with `{{skills}}` / `{{include}}` template resolution) and stores the rendered text under `system_prompt` in `agent-job.config.json`. Named volumes can't render host-side, so the container reads the pre-rendered prompt from the config file. Both callers (cron/trigger via `lib/actions.js` and HTTP via `api/index.js`) just forward `scope` — they do not pre-render.
 
 **Git tree construction**: Uses GitHub's Git Data API (not REST content API) to create commits. Builds a tree with `base_tree` to preserve existing files, adding only `logs/{agentJobId}/agent-job.config.json`. This file is the single source of truth for job metadata.
 
-**Local Docker launch**: After pushing the `agent-job/*` branch, launches a Docker container locally (fire-and-forget). Uses a named volume for workspace, cleaned up after container exits.
+**Local Docker launch**: After pushing the `agent-job/*` branch, launches a Docker container locally (fire-and-forget). Uses a named volume for workspace, cleaned up after container exits. `runAgentJobContainer()` sets `USER_ID` from the config when present so the running agent can attribute spawned child jobs / DMs back to the originator.
 
 ## github.js — GitHub API & PAT Probing
 

package/lib/tools/github.js

@@ -234,18 +234,25 @@ async function listRepositories() {
 }
 
 /**
- * List branches for a repository.
+ * List branches for a repository. Paginates up to MAX_PAGES (1000 branches)
+ * so repos with >100 branches return their full list to the dropdown.
  * @param {string} repoFullName - e.g. "owner/repo"
  * @returns {Promise<{name: string, isDefault: boolean}[]>}
  */
 async function listBranches(repoFullName) {
   const [owner, repo] = repoFullName.split('/');
-  const [branches, repoInfo] = await Promise.all([
-    githubApi(`/repos/${owner}/${repo}/branches?per_page=100`),
-    githubApi(`/repos/${owner}/${repo}`),
-  ]);
+  const PER_PAGE = 100;
+  const MAX_PAGES = 10;
+  const repoInfoPromise = githubApi(`/repos/${owner}/${repo}`);
+  const all = [];
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const batch = await githubApi(`/repos/${owner}/${repo}/branches?per_page=${PER_PAGE}&page=${page}`);
+    all.push(...batch);
+    if (batch.length < PER_PAGE) break;
+  }
+  const repoInfo = await repoInfoPromise;
   const defaultBranch = repoInfo.default_branch;
-  return branches.map(b => ({
+  return all.map(b => ({
     name: b.name,
     isDefault: b.name === defaultBranch,
   }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thepopebot",
-  "version": "1.2.76-beta.36",
+  "version": "1.2.76-beta.38",
   "type": "module",
   "description": "Create autonomous AI agents with a two-layer architecture: Next.js Event Handler + Docker Agent.",
   "bin": {

package/setup/CLAUDE.md

@@ -19,20 +19,25 @@ Settings DB defaults to `data/db/thepopebot.sqlite` (relative to project root).
 
 ## Sync Target Types
 
-Config values are synced to different targets via `lib/sync.mjs`:
+Config values are synced to different targets via `lib/sync.mjs`. The mapping lives in `lib/targets.mjs` (`CONFIG_TARGETS`):
 
-| Target | Storage | Example |
-|--------|---------|---------|
-| `env` | `.env` file | `APP_URL`, `GH_OWNER` |
-| `db` | `settings` table (plaintext) | Non-secret config |
-| `db_secret` | `settings` table (encrypted) | `GH_TOKEN` |
-| `github_secret` | GitHub repo secret | `GH_TOKEN`, `WEBHOOK_SECRET` |
-| `github_variable` | GitHub repo variable | `LLM_PROVIDER`, `LLM_MODEL` |
+| Flag | Storage | Example |
+|------|---------|---------|
+| `env: true` | `.env` file | `APP_URL`, `GH_OWNER`, `GH_REPO`, `APP_HOSTNAME` |
+| `db: true` | `settings` table (plaintext) | `LLM_PROVIDER`, `LLM_MODEL`, `CUSTOM_OPENAI_BASE_URL`, `AGENT_BACKEND` |
+| `dbSecret: true` | `settings` table (AES-256-GCM encrypted) | All API keys, OAuth tokens, Telegram bot token, `GH_WEBHOOK_SECRET` |
+| `variable: true` | GitHub repo variable | `APP_URL`, `AUTO_MERGE`, `ALLOWED_PATHS`, `RUNS_ON` |
+| `secret: true` / `secret: 'NAME'` | GitHub repo secret | `GH_TOKEN`, `GH_WEBHOOK_SECRET` |
+| `firstRunOnly: true` | Only written on first setup | `AUTO_MERGE`, `ALLOWED_PATHS` |
 
-A single config field can sync to multiple targets (e.g., `GH_TOKEN` → `db_secret` + `github_secret` + `env`).
+A single field can carry multiple flags (e.g., `GH_TOKEN` → `env` + `dbSecret`; `GH_WEBHOOK_SECRET` → `dbSecret` + `secret`).
+
+GitHub-side state is intentionally minimal: only `GH_TOKEN` and `GH_WEBHOOK_SECRET` are mirrored to GitHub Secrets (consumed by CI workflows). Earlier `AGENT_*` mirrors and the `LLM_PROVIDER` / `LLM_MODEL` / `CUSTOM_OPENAI_BASE_URL` / `AGENT_BACKEND` GitHub variables were removed — agent-job containers run locally and read everything from the DB, so those mirrors had no consumers.
+
+The fine-grained PAT must include the **Variables: Read** scope, otherwise `/admin/github/variables` shows every variable as "Not set" and surfaces the underlying API error.
 
 ## Adding New Config Fields
 
-1. Add the field definition to the sync config map in `lib/sync.mjs` with its target(s)
-2. If it needs user input, add a prompt step in `setup.mjs`
-3. Run `syncConfig()` to write to all targets
+1. Add the field to `setup/lib/targets.mjs` `CONFIG_TARGETS` with its flags.
+2. If it needs user input, add a prompt step in `setup.mjs`.
+3. Run `syncConfig()` to write to all targets.

package/setup/lib/telegram.mjs

@@ -1,15 +0,0 @@
-// Re-export Telegram API helpers from the package (single source of truth).
-// The CLI setup wizard shares these helpers with the admin UI server actions.
-export {
-  validateBotToken,
-  setTelegramWebhook,
-  getTelegramWebhookInfo,
-  deleteTelegramWebhook,
-} from '../../lib/tools/telegram.js';
-
-/**
- * Get BotFather URL for creating a new bot
- */
-export function getBotFatherURL() {
-  return 'https://t.me/BotFather';
-}