@tekmidian/pai 0.39.1 → 0.40.0

package/docs/provider-abstraction.md

@@ -0,0 +1,87 @@
+# Provider Abstraction
+
+## What this layer achieves
+
+The entire assistant stack — interactive sessions, workers, follow panes, hooks, MCP tools and the statusline — runs on **any provider that speaks the Anthropic Messages protocol**, not just Anthropic. This has been demonstrated end-to-end on a third-party `glm` endpoint serving a 1M-context model: the interactive session, every delegated worker, the daemon-side background calls (summaries, context handovers, knowledge-graph extraction) and all instrumentation run against that provider, with nothing falling back to a vendor login.
+
+What that buys:
+
+- **No single-vendor lock-in.** Providers are entries in a registry (`src/workers/config.ts`): protocol (`anthropic`/`openai`), engine (`claude`/`codex`), model ids, key files, cost tiers, capability tags, quota probes. Switching is `pai worker providers use <name>`; disabling routing entirely is `pai worker off`.
+- **Plan/quota-aware instrumentation.** The statusline reads the *active provider's* real plan utilization (5-hour rolling window and weekly quota with reset times), not a hardcoded vendor endpoint.
+- **Cost routing per task class.** Work is dispatched by class (`draft`, `spotcheck`, `complex`, …); each class maps to a provider and model, so cheap work lands on cheap models without touching code.
+- **Provider swaps are configuration, not surgery.** Every seam that used to assume one vendor — daemon LLM spawns, compaction-history family detection, context-window defaults, tier aliases — has been patched at protocol level (see below), so a new provider is a registry entry plus a key file.
+
+OpenAI-protocol providers are reached through the translating proxy (`src/workers/proxy/`), and the Codex engine (`src/workers/codex.ts`) normalizes its events into the same shape — both are first-class in the registry.
+
+## Tools
+
+### Worker provider/model routing
+
+`pai worker run --class <class>` picks the provider and model for a job by task class. The standard classes (`WORKER_CLASSES`, `src/workers/config.ts:126`): `draft`, `plan`, `implement`, `review`, `research`, `spotcheck`, `simple`, `complex`. `--provider` and `--model` override for a single call.
+
+Model ids are configuration, not code. Two surfaces manage them:
+
+- **CLI** — `pai worker model` (`src/cli/commands/worker/model.ts`): no args lists the active provider with its `default` and `fast` model ids; `model <id>` sets the default; `model fast <id>` sets the fast slot; `--provider` targets a non-active provider.
+- **MCP** — the `worker_model` tool (`src/daemon-mcp/tools/worker-model.ts`): `action: get|set`, `slot: default|fast`, optional `provider`.
+
+```text
+$ pai worker model
+glm (active)
+  default: glm-5.3[1m]
+  fast:    glm-5.3-flash
+
+$ pai worker model glm-5.4
+$ pai worker model fast glm-5.4-flash --provider glm
+```
+
+The `fast` slot is what cheap classes resolve to; the runner also honors the platform's tier aliases by pinning `ANTHROPIC_DEFAULT_{HAIKU,SONNET,OPUS}_MODEL` to the provider's models in the spawn environment (`src/workers/run-env.ts`).
+
+### Provider-aware statusline
+
+`statusline-command.sh` derives everything it can from the session's model id instead of assuming one vendor:
+
+- **Plan utilization** — glm sessions fetch the provider's plan quota (5-hour window and weekly credit window, `nextResetTime` rendered as reset times); claude models keep the existing Anthropic OAuth path. Each source has its own 60-second cache. On fetch failure the provider windows show `?` rather than silently falling back to another plan's numbers. `PAI_ZAI_QUOTA_URL` overrides the endpoint (kill switch / testing).
+- **Context window from the model id** — a `[1m]` variant suffix means a 1,000,000-token window (`statusline-command.sh:126`); ids with no marker keep the previous default. The same derivation lives in TypeScript as `contextWindowFromModelId()` (`src/utils/model-window.ts`), so the session hooks and the worker meter agree with the statusline.
+- **`(N% left)`** — remaining context until auto-compact, computed against that derived window.
+- **Worker row** — line 4 lists the workers this session launched, running ones with their current step (`pai worker status-line`, `statusline-command.sh:634`).
+
+### Seam patches
+
+The seams that previously hardcoded one vendor, now patched:
+
+- **Daemon LLM spawns route through the provider registry** — `src/workers/daemon-llm.ts` builds the spawn plan for session summaries (`src/daemon/session-summary-worker.ts`), context handovers (`src/daemon/context-handover-worker.ts`) and KG extraction (`src/memory/kg-extraction.ts`) via `buildRunEnv()` (`src/workers/run-env.ts`): provider base URL and token, the provider's concrete model id instead of a tier alias, and class-appropriate timeouts. With no provider configured it falls back to the historical bare-alias behaviour minus the vendor API key.
+- **Compaction-history family detection accepts any provider model** — `modelFamily()` (`src/hooks/ts/lib/context-fill.ts:379`) derives a stable family key from the model id itself, stripping any bracketed variant suffix (`glm-5.3[1m]` → `glm-5.3`), instead of allowlisting `claude-*` and discarding everything else as "foreign". A provider-model session keeps its measured compaction history.
+- **Context-window defaults derived from the model id** — `src/utils/model-window.ts` is the single helper; consumers are the session hooks (`context-fill.ts`) and the provider schema default (`src/workers/config.ts`). The statusline derives its window the same way, instead of writing a single assumed size into the state file for every model it does not recognize.
+- **Tier aliases map provider models into the cheap/standard tiers** — `modelToClass()` (`src/workers/agents.ts`) resolves an agent's model through the provider registry (`fast` → cheap tier, `default` → standard) and logs once, then falls back to the standard class, instead of silently dropping the hint for unknown ids.
+
+### Delegation instruments
+
+- **Agent-tool gate** — `src/hooks/ts/pre-tool-use/route-agents-to-worker.ts` (PreToolUse, Agent matcher) denies in-process subagents whenever worker providers are configured, so no delegated work runs on the vendor login; the deny reason tells the orchestrator to use `pai worker run` instead. `ALLOW_ANTHROPIC_AGENTS=1` bypasses it for one session. Every decision is appended to the routing ledger (`pai worker log`).
+- **Worker exemption marker** — every worker spawn carries `PAI_WORKER=1` (`src/workers/run-env.ts:47`; `src/workers/codex.ts:50` for the Codex engine). `isWorkerSession()` (`src/hooks/ts/lib/worker-session.ts`) makes all per-session hooks (autosave, stop bookkeeping, compaction state) skip disposable workers, so the gate and the bookkeeping never fight the workers themselves.
+- **Post-compaction reinjection** — `src/hooks/ts/session-start/post-compact-inject.ts` (SessionStart, matcher `compact`) replays the state the PreCompact hook saved, so a compacted orchestrator session resumes with its context intact. The live worker list stays visible in the statusline's worker row and via `pai worker ps` / `pai worker follow <id>`.
+
+### Session-level instruments (deployed config)
+
+Two further instruments are deployed configuration in the PAI config dir rather than repo code, so a tree-only audit misses them:
+
+- **Edit-delegation guard** — a PreToolUse hook (`route-edits-to-worker`) blocks `Edit`/`MultiEdit`/`Write` on files inside any git work tree for orchestrator sessions, while worker sessions are exempt via the `PAI_WORKER=1` marker set on every worker spawn. Code changes route through workers mechanically.
+- **Compact recovery** — on `SessionStart(compact)` a hook injects the live `pai worker ps --all` output into the session context, so a session resuming from compaction immediately sees every running worker.
+
+### Live worker panes
+
+`pai worker follow` (`src/cli/commands/worker/index.ts:165`) attaches a chat pane to a worker, rendered by `src/workers/viewer.ts`, `pane.ts`, `render.ts` and `chatui.ts`:
+
+- **Transcript with stamped gutter** — every event line carries a dim `HH:MM:SS │ ` stamp from the event's own timestamp, with continuation padding for wrapped text (`render.ts:135`); the pane's bar runs unbroken down its full height (`render.ts:139`).
+- **Prompt row** — `› ` with readline line editing. Plain text is *said* to a running worker; `/resume <text>` continues a finished one; `/status` prints a one-line status (`chatui.ts`).
+- **Status ticker** — a fixed bottom row showing elapsed time, current intent and tool (`$ bun run test` …) plus the worker's provider/model and context meter (`tickerText()`, `render.ts:183`; meter data from `src/workers/status.ts`, whose window comes from the run's init event or the provider default). A finished worker freezes the row with ✓/✗.
+- **Resize-safe redraw** — on terminal resize the viewer re-reads the geometry, clears the stale transcript and refills it from events (`viewer.ts:735`), so the fixed prompt/ticker rows and the scroll-region transcript stay consistent at any size.
+
+## In action
+
+![A live session on a third-party 1M-context model: the provider-aware statusline (plan quota windows with reset times, derived context window, worker row) above worker follow panes with stamped transcript, prompt row and status ticker.](images/provider-abstraction-live.png)
+
+## Current limits
+
+The layer is proven against one non-Anthropic provider so far (the `glm` endpoint); other Anthropic-protocol providers are expected to work but have not been exercised end-to-end, and OpenAI-protocol providers additionally depend on the translating proxy. Instrumentation still special-cases per-provider quota endpoints as providers are added. The seam audit that drove these patches lives outside this repository; new seams are patched as they surface, and each patch carries a unit test pinning the provider-neutral behaviour (`src/workers/daemon-llm.test.ts`, `src/workers/model.test.ts`, `src/workers/agents.test.ts`, `src/hooks/ts/lib/context-fill.test.ts`).
+
+For the full worker command reference see [worker.md](worker.md) and [commands/worker.md](commands/worker.md).

package/docs/provider-independence-details.md

@@ -0,0 +1,330 @@
+# Provider Independence — Details
+
+Everything technical about provider independence: what switches, the tools,
+the configuration, the internals. The human-facing page is
+[provider-independence.md](provider-independence.md).
+
+## Switch what?
+
+Two levels, one provider registry. Both switch by sentence or by command —
+never by editing code:
+
+| Level | What runs on the provider | Switch with |
+| --- | --- | --- |
+| The crew | delegated workers — research, drafting, implementation, review, spotchecks | `worker_providers` (use): "Use glm for the workers from now on." |
+| The orchestrator | the session itself — the interactive chat you are typing into | start it with `glm` (the shim for `pai worker run`), or pick a project with `pai` — the picker follows the active provider |
+
+The main session orchestrates, reviews and merges; workers do the work —
+unless the session itself runs on a provider too, in which case everything is
+off the Anthropic account.
+
+### The crew — `worker_providers` add / use
+
+- **Add once.** "Add a worker provider named glm, base URL <url>, model
+  <model>, here is the key: <token>" → `worker_providers` (add). The key is
+  parked in `~/.config/pai/keys/<name>` (mode 0600); the config records only
+  the path. OpenAI-compatible endpoint? Say "upstream URL" — PAI routes it
+  through its local translating proxy. The first provider added also turns
+  worker routing on and seeds the nine classes (`addProvider`,
+  `src/workers/providers.ts:51`); from then a PreToolUse hook denies every
+  in-process subagent.
+- **Use.** "Switch the fleet to glm." → `worker_providers` (use): sets
+  `workers.active` (`useProvider`, `src/workers/providers.ts:170`); classes
+  without an explicit target follow.
+- **Test.** "Is glm alive?" → `worker_providers` (test): a one-word pong
+  probe, latency, OK/FAILED.
+- **Off.** "Turn workers off." → `worker_toggle`: subagents run on Anthropic
+  again; the registry is kept.
+
+### The orchestrator — the session itself
+
+There is no in-session switch: a session runs on a provider by being
+**started that way**. The launcher is `glm` — a shim in `~/.local/bin`
+written by `pai worker install` (`src/workers/install.ts:119` body
+`exec pai worker run "$@"`; installed names `glm`, `glm-run`, `glm-ps`,
+`glm-log`, `worker-say`, `:125`).
+
+`pai worker run` without `-p` starts an **interactive** Claude Code session:
+it spawns `claude` with the terminal inherited (`stdio: "inherit"`,
+`src/workers/run.ts:452`) — that process *is* the chat pane, not a subagent
+of it (`origin: "chat"`, `run.ts:394`). No MCP restriction applies.
+
+The `pai` project picker follows the active provider the same way: its
+launch keys start an interactive worker run in the chosen directory
+(`w` forces it, `a` forces plain `claude`).
+
+What actually puts it on the provider is the spawn environment
+(`buildRunEnv`, `src/workers/run-env.ts`):
+
+| Env var | Value | Where |
+| --- | --- | --- |
+| `ANTHROPIC_API_KEY` | deleted — the Anthropic key never reaches a provider session | `run-env.ts:19` |
+| `ANTHROPIC_BASE_URL` | the provider's base URL; the local proxy's URL for OpenAI-protocol providers | `run-env.ts:25,37` |
+| `ANTHROPIC_AUTH_TOKEN` | the token read from the provider's key file (proxy runs: placeholder) | `run-env.ts:40` |
+| `ANTHROPIC_DEFAULT_HAIKU_MODEL` / `_SONNET_MODEL` / `_OPUS_MODEL` | the provider's fast/default models — every model slot maps to the provider | `run-env.ts:41-43` |
+| `ENABLE_TOOL_SEARCH` | `true` in interactive runs; headless runs get `PAI_WORKER=1` instead | `run-env.ts:47-49` |
+
+- **Model.** `--model <provider default>` is passed unless you name one
+  (`run.ts:438-439`). A `[1m]` suffix on the model id (`glm-5.3[1m]`) selects
+  the 1,000,000-token window variant: the suffix is read wherever a window is
+  needed (`contextWindowFromModelId()`, `src/utils/model-window.ts:33`) and
+  stripped for the family name (`stripModelVariant()`, `:19`).
+- **Machine-wide instead of per-session.** `worker_fallback` (on) writes the
+  same env into the `env` block of `~/.claude/settings.json`
+  (`src/workers/fallback.ts:90-94`; path override `CLAUDE_SETTINGS_PATH` for
+  dry runs, `:46`), so every NEW Claude Code process — interactive,
+  task-bus, daemon summarizer — runs on the provider. `off` restores the
+  saved previous state. Running sessions keep their provider until
+  restarted; worker routing is unchanged while on.
+- **Bypass.** `ALLOW_ANTHROPIC_AGENTS=1` in the environment re-enables the
+  Agent tool for one session.
+
+## Tools (MCP)
+
+Everything here happens in chat: you say the sentence, the session calls the
+tool — you never name the tool yourself. These are the **twelve `worker_*`
+tools** the pai MCP server registers (`src/daemon-mcp/index.ts:804-1334`);
+there is no worker surface outside them. Parameter names are the schema's
+own.
+
+### At a glance
+
+| Tool | You say | What it does |
+| --- | --- | --- |
+| `worker_status` | "How is the worker system doing?" | On/off, active provider, providers, today's run tally, running workers with waiting handoffs |
+| `worker_providers` | "Switch the workers to glm." | Manage providers: list / add / update / remove / use / enable / disable / test |
+| `worker_fallback` | "Run everything on glm." | Machine-wide: every NEW Claude Code process on a provider — or back on the Anthropic login |
+| `worker_classes` | "Make spotchecks cheaper." | Map task classes to providers or routing constraints |
+| `worker_model` | "Put glm on the 1M-context model." | Show or set a provider's model ids (default and fast slots) |
+| `worker_run` | "Fix the black buttons bug." | Start a worker or chain; returns the id immediately |
+| `worker_handoff` | (inside a worker) "Ask the parent whether …" | Send a proposal / question / blocker / result up to the parent |
+| `worker_toggle` | "Turn workers off." | Route subagents to workers (on) or back to Anthropic (off) |
+| `worker_ps` | "What are my workers doing?" | Running workers plus the last finished |
+| `worker_replay` | "What did 3390 do?" | Transcript of one worker |
+| `worker_say` | "Tell 3390 to skip the docs." | One message to a running worker, mid-run |
+| `worker_resume` | "Have 3390 also update the docs." | Continue a finished worker, context intact |
+
+### Tool details
+
+#### `worker_status` — the state page
+No parameters. Workers on/off, active provider, provider list, today's tally
+(started / ok / failed, hook denied / allowed / rerouted), running workers
+with `◆N` waiting handoffs. Use it before delegating to see what routing
+will choose.
+
+#### `worker_providers` — manage providers
+`action` (default `list`): **list** · **add** · **update** · **remove** ·
+**use** · **enable** · **disable** · **test**. `name` is required for every
+action but `list`.
+
+- **add** — needs `name`, `model`, and `key_file` or `key`. `base_url` for an
+  Anthropic-protocol endpoint, or `upstream_url` with `protocol=openai`
+  (routed through the local proxy). Optional: `engine` (`claude`|`codex`),
+  `fast_model`, `context_window` (the meter; unset hides it unless the init
+  event announces one), `env`, `note`, `quota_probe`, `cost_tier` (1 cheapest
+  … 5), `tags` (`code`, `vision`, `image-gen`, `long-context`, `fast`,
+  `reasoning`). The first provider added also turns routing on and seeds the
+  classes.
+- **update** — `cost_tier` and/or `tags`.
+- **use** — make it active; unset classes follow it.
+- **enable / disable** — in or out of auto-routing.
+- **test** — one-word pong probe: latency, OK/FAILED.
+- **remove** — drop it, and any classes pointing at it.
+
+#### `worker_fallback` — the machine-wide switch
+`action` (default `status`): **on** · **off** · **status**; `on` takes
+`provider` (default: active). See the orchestrator section above for exactly
+what it writes and restores.
+
+#### `worker_classes` — map classes to providers
+`action` (default `list`): **list** · **set** · **unset**. `set` takes
+`class` plus either `target` (`<provider>` or `<provider>/fast`) or routing
+constraints — `max_cost_tier` (1–5) and/or `require_tags` — with which
+auto-routing picks any qualifying provider. `unset` frees a class back to
+the active provider.
+
+#### `worker_model` — model slots
+`action` (default `get`): **get** — model ids of one provider (`provider`,
+default active) or all when omitted; **set** — needs `model`, `slot` picks
+`default` or `fast`. `[1m]` suffix = 1M window, derived from the id.
+
+#### `worker_run` — start work
+`prompt` (required — the task, self-contained). Optional: `chain`
+(`draft,implement` or `draft,implement,review`), `class` (the nine below),
+`label` (shown in `worker_ps` and the statusline — always give one), `cwd`,
+`allowed_tools` (comma-separated allowlist), `mcp` (servers/sets the worker
+may load). Returns the id at once; the run is a background task — the result
+arrives later as a task notification (`result` plus a parsed `report`:
+changed paths, ✓/✗ checks, open items). The orchestrator ends its turn
+instead of waiting, and reviews the diff itself — workers never merge their
+own work.
+
+#### `worker_handoff` — from inside a worker
+`kind` (required): `proposal` · `question` · `blocker` · `result`; `text`
+(required, one paragraph); optional structured `data`. Lands in the parent's
+inbox. Only works inside a worker — no sideways or downward path. Results
+are sent automatically when you finish; send one yourself only for mid-run
+findings.
+
+#### `worker_toggle` — routing switch
+`enabled` (required). `true`: the Agent-tool hook denies in-process
+subagents and rewrites them to workers. `false`: they run on Anthropic
+again. Registry kept either way.
+
+#### `worker_ps` — the list
+Optional `all`: `true` = every session's workers, default this session's.
+Running workers show id, provider, age, turns, current tool; the last
+finished is included.
+
+#### `worker_replay` — one transcript
+`id` (required), optional `tail` (last N rendered lines, 1–2000). Plain
+text: tool calls, short outputs, result.
+
+#### `worker_say` — talk to a running worker
+`id`, `text` (both required). Lands on the worker's open stdin as a user
+message, mid-run, without breaking its stream. Fails with an explanation
+when the worker finished — then `worker_resume`.
+
+#### `worker_resume` — continue a finished worker
+`id`, `text` (both required). `claude --resume` on the same provider, same
+session, context intact; returns the new worker id. Not for running workers.
+
+## Configure
+
+Everything lives in the `workers` section of `~/.config/pai/config.json`
+(`readWorkersSection` / `writeWorkersSection`, `src/workers/config.ts:619`);
+every sentence and tool above writes it atomically — no hand-editing.
+
+**Classes** (`WORKER_CLASSES`, `src/workers/config.ts:131`):
+
+| Class | Work |
+| --- | --- |
+| `draft` · `plan` | spec writing, planning |
+| `implement` · `complex` | code (get their own git worktree on `worker/<id>`) |
+| `review` | reads the diff |
+| `research` | web research (give it `WebSearch,WebFetch`) |
+| `spotcheck` · `simple` | fast verification, small jobs |
+| `image` | image generation |
+
+A class maps to `<provider>`, `<provider>/fast`, or to constraints
+(`maxCostTier` 1–5, `requireTags`, per-class `order`). Unset classes follow
+the active provider; `active: "auto"` routes by `workers.routing.order`
+instead.
+
+**Provider fields** (registry entry, `parseProvider`,
+`src/workers/config.ts:264`): protocol, base URL (or upstream URL for the
+proxy), key file path, model slots (default / fast, `[1m]` suffix for the
+1M window), engine, `cost_tier`, `tags`, extra `env`, `context_window`.
+
+**Defaults you inherit** (`src/workers/config.ts:209-226`):
+
+| Area | Default |
+| --- | --- |
+| Routing | cooldown 30 min after a quota/rate failure, `retryOnQuota` true |
+| Sub-worker tree | depth 2, 4 children per parent |
+| Follow pane | font 13 pt, auto-exit 60 s |
+| Logs | `~/.claude/logs/workers` |
+
+**Environment variables:**
+
+| Var | Effect |
+| --- | --- |
+| `PAI_WORKER=1` | carried by every headless spawn — marks the worker session, exempts it from orchestrator-only hooks (`src/workers/run-env.ts:47`) |
+| `ALLOW_ANTHROPIC_AGENTS=1` | re-enables the Agent tool for one session |
+| `ENABLE_TOOL_SEARCH=true` | set in interactive provider runs (`run-env.ts:49`) |
+| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` | every provider spawn (`run-env.ts:45`) |
+| `CLAUDE_SETTINGS_PATH` | dry-run target for `worker_fallback` |
+
+## How it works
+
+One orchestrator, many workers, split made mechanical by four hooks:
+
+| Hook | Enforces | Where |
+| --- | --- | --- |
+| PreToolUse (Agent) | every in-process subagent denied while providers are configured; the deny reason prints the `pai worker run` line to use instead | `src/hooks/ts/pre-tool-use/route-agents-to-worker.ts`, deployed `${PAI_DIR}/Hooks/route-agents-to-worker.mjs` |
+| PreToolUse (Edit/Write) | no code edits by the orchestrator inside a git work tree; `PAI_WORKER=1` sessions are exempt | `${PAI_DIR}/Hooks/route-edits-to-worker.mjs` (deployed config) |
+| SessionStart (compact) | saved state replayed and the live worker list injected — a compacted orchestrator still sees every worker | `src/hooks/ts/session-start/post-compact-inject.ts`, `${PAI_DIR}/Hooks/post-compact-workers.mjs` |
+| PreToolUse (TaskOutput) | blocking waits denied unless `block: false` — end the turn; the result arrives as a task notification | `${PAI_DIR}/Hooks/block-taskoutput-wait.mjs` |
+
+Every routing decision lands in the routing ledger (`pai worker log`). A
+chain `draft,implement[,review]` gives each stage its own worker — own id,
+own follow pane, tree in the worker list; a failing stage stops the chain.
+Writing classes work in their own git worktree on `worker/<id>`; merging or
+discarding is a deliberate operator (or orchestrator) action.
+
+The **statusline** carries the worker row (line 4):
+
+```
+glm ▶1  #3390 unlabeled 30s · interactive   ✓74 ✗4 today
+```
+
+Segments: provider badge (`glm`; `workers` when mixed) · `▶N` this
+terminal's running workers with a live pid · short id · label · age ·
+current step · today's finished count. Full legend (`◆N` handoffs, `ctx`
+meter, `↳` sub-workers): the *Status line* section of
+[worker.md](worker.md).
+
+What else follows the active provider — statusline plan windows,
+daemon-side summarizer calls, compaction history, the translating proxy:
+[provider-abstraction.md](provider-abstraction.md).
+
+### Code map
+
+| What | Where |
+| --- | --- |
+| Provider registry, classes (`WORKER_CLASSES`) | `src/workers/config.ts:131` |
+| Config read/write, `workers` section | `src/workers/config.ts:619` |
+| Provider validation (`parseProvider`) | `src/workers/config.ts:264` |
+| First-provider takeover (enabled + active + seeded classes) | `src/workers/providers.ts:51` (`addProvider`) |
+| `providers use` (sets `workers.active`) | `src/workers/providers.ts:170` (`useProvider`) |
+| `pai worker on/off` (`setWorkersEnabled`) | `src/workers/providers.ts:279` |
+| Runner / chain / agent definitions | `src/workers/run.ts`, `src/workers/chain.ts`, `src/workers/agents.ts` |
+| Spawn env — base URL, token, model pins | `src/workers/run-env.ts` |
+| Machine-wide fallback (settings.json) | `src/workers/fallback.ts` |
+| Shims (`glm`, `glm-run`, …) installer | `src/workers/install.ts` |
+| Worktrees and merge | `src/workers/worktree.ts` |
+| CLI surface (`run`, `ps`, `follow`, `replay`, `merge`, `discard`) | `src/cli/commands/worker/index.ts` |
+| Providers / classes CLI | `src/cli/commands/worker/providers.ts:124,334` |
+| Model slots CLI (`pai worker model`) | `src/cli/commands/worker/model.ts` |
+| Statusline worker row | `src/workers/render.ts`, `statusline-command.sh` (line 4), built `${PAI_DIR}/worker-status-line.mjs` |
+| Context window from model id (`[1m]`) | `src/utils/model-window.ts` |
+| Agent-tool gate hook (repo) | `src/hooks/ts/pre-tool-use/route-agents-to-worker.ts` |
+| Post-compact reinjection (repo) | `src/hooks/ts/session-start/post-compact-inject.ts`, `src/hooks/ts/lib/context-fill.ts` |
+| Worker-session exemption | `src/hooks/ts/lib/worker-session.ts` |
+| Deployed hooks (config, not repo) | `${PAI_DIR}/Hooks/route-edits-to-worker.mjs`, `block-taskoutput-wait.mjs`, `post-compact-workers.mjs` — registered in `${PAI_DIR}/settings.json` |
+| MCP tool surface — all 12 `worker_*` tools | `src/daemon-mcp/index.ts:804-1334` (`worker_model` handler: `src/daemon-mcp/tools/worker-model.ts`) |
+| Neighbour docs | [provider-independence.md](provider-independence.md), [provider-abstraction.md](provider-abstraction.md), [worker.md](worker.md), [commands/worker.md](commands/worker.md) |
+
+## CLI fallback
+
+For scripts and terminals outside sessions — the twin of a tool above; flags
+live in [commands/worker.md](commands/worker.md). (`worker_status` has no
+single twin; `pai worker ps` + `pai worker log` show the same facts.)
+
+| Command | Twin of |
+| --- | --- |
+| `pai worker run [claude-args…]` | `worker_run` — and the only place a one-call `--provider` override exists |
+| `pai worker ps [--all]` | `worker_ps` |
+| `pai worker replay <id> [--tail n]` | `worker_replay` |
+| `pai worker say <id> <text>` | `worker_say` |
+| `pai worker resume <id> <text>` | `worker_resume` |
+| `pai worker handoff <json>` | `worker_handoff` |
+| `pai worker providers <list\|add\|update\|remove\|use\|enable\|disable\|test>` | `worker_providers` — keys via `--key-file`, never pasted |
+| `pai worker classes <list\|set\|unset>` | `worker_classes` |
+| `pai worker model [what] [model]` | `worker_model` |
+| `pai worker on` / `pai worker off` | `worker_toggle` |
+| `pai worker fallback <on [provider]\|off\|status>` | `worker_fallback` |
+
+Terminal-only (no tool equivalent):
+
+| Command | What it does |
+| --- | --- |
+| `pai worker watch` | `ps` refreshed every 2 seconds |
+| `pai worker follow [id]` / `pai worker pane [id]` | live transcript pane for one worker or this session's |
+| `pai worker log [all\|tail\|<id>]` | the routing ledger, or one worker's raw event stream |
+| `pai worker merge <id>` / `pai worker discard <id>` | land a worker's worktree branch in the original checkout, or drop it entirely |
+| `pai worker controls <id> you\|me` | hand the desktop controls (clickr) to a worker, or take them back |
+| `pai worker status-line [term] [cwd]` | one-line worker summary for a status bar (called by `statusline-command.sh`) |
+| `pai worker proxy [stop]` | the local Anthropic↔OpenAI proxy |
+| `pai worker mcp [list]` | MCP servers/sets workers may load |
+| `pai worker install` | migration: Agent hook in settings.json, `~/.local/bin` shims (`glm`, …), old script cleanup |

package/docs/provider-independence.md

@@ -0,0 +1,75 @@
+# Provider Independence
+
+How to free yourself from Claude — so a maxed-out subscription stops being your problem. How to run any cloud model and any local model inside your Claude Code (or OpenCode) harness. How to run models in parallel, each doing what it is best at — all of it purely local, no need for yet another Hermes-or-whatever harness. How to have workers run by default, visibly, each with its own chat you can talk to.
+
+My journey into PAI and AIBroker started nine months ago, when OpenClawd burned through all my credits in four hours. I decided then and there that there had to be a better way: instead of buying API tokens, use the Claude Max subscription I was already paying for.
+
+Nine months later, I hit the next wall: maxing out Claude Max itself. The next level of independence was required. I built it — in one day. Here is what happened.
+
+I started my Thursday at 5am, which is normal, and at about 80%, which is not.
+
+That 80% is not motivation — although that was certainly higher. It is the weekly usage of my Claude Max 200 subscription.
+
+With two days to go until the Saturday 8am reset, I was getting worried. Last week I had already hit 100% — despite all my efficiency gains, including inventing my own "Agentish" language.
+
+By 9am I was above 90%. There was no way I would make it to the reset.
+
+So I decided to solve this problem instead of waiting it out. By 10pm I was at 97% — a number that has not moved since noon, because since noon, almost nothing has run on Claude.
+
+This is how I did it.
+
+I made myself independent of Claude and Fable. They are great — but I hate being locked in, and I suspect most of us do. I want to decide which model I use: Claude, GLM, Grok, whatever. I need to abstract away from that choice.
+
+Fable was — and is — great, but it burns tokens. And Opus on its own is so unbelievably dumb that I had taken to letting Fable do everything, even forcing it to not use agents — burning tokens even faster.
+
+So the requirements were:
+
+1. **Provider independence.** Switch to any model at any time — not only for agents, but for the main orchestrator session too.
+2. **Cloud and local.** Any cloud model, and local models.
+3. **Visibility.** Really see what each worker is doing — not Claude Code's click-into-a-worker-and-make-sense-of-it, but every worker in a side pane, automatically.
+4. **Direct chat.** Talk to any worker while it runs.
+5. **Hardening.** Each worker in its own worktree, so parallel work cannot destroy itself.
+6. **Forced orchestration.** Not just ask the orchestrator to delegate — deterministically enforce that it spawns workers.
+7. **Cost routing.** Automatically pick cheaper workers for simpler tasks.
+8. **Keep the harness.** Stay on Claude Code (I could have switched to OpenCode — turns out it was not even necessary).
+
+The whole implementation cost 7 of my last 10 percentage points of Claude Max 200. Then I switched to GLM for everything else. And what can I say — it works beautifully.
+
+---
+
+The rest of this page is the operator's guide: switching providers, starting sessions, and the three copy-paste steps to your own setup.
+
+> My AI budget hit 91% before lunch. So I changed one rule: the expensive
+> assistant keeps the thinking, a cheaper crew does the building. The feature
+> shipped anyway.
+>
+> Your AI bill is not a fact of nature. It is a design decision.
+
+Your assistant runs its helper crew on whichever AI provider you choose —
+and so can the session itself.
+
+## Switching
+
+- **The crew.** Once, at the start: "Add a worker provider named <provider> — here
+  is the key." Then: "Use <provider> for the workers from now on."
+- **The session itself.** Start it with the `<provider>` command — the shim for
+  `pai worker run` — or just pick a project with `pai`: the picker follows
+  the active provider too, so the whole session, you included, runs on it.
+
+Swapping back — or to any other provider — is one sentence for the crew, and
+starting `claude` again for the session.
+
+## A day with the crew
+
+- "Fix the login timeout bug." — a worker named *fix login timeout* starts; the status line shows its name and current step, live.
+- "What are my workers doing?" — a short list, by name.
+- "Tell fix login timeout to also check the retry path." — lands mid-run; the worker adapts.
+- "Show me what it changed." — the diff comes back for your review.
+- "Stop using workers for now." — the crew stands down.
+
+![The worker row live in the status line.](images/workers.png)
+
+## Further
+
+- [How it works — full tool reference](provider-independence-details.md)
+- [The provider layer, in depth](provider-abstraction.md)

package/docs/worker.md

@@ -383,8 +383,8 @@ behaviour — no prompt row, no ticker, stdin still the operator channel.
 Any worker may start its own workers: the runner exports `PAI_WORKER_ID` in
 every worker's environment, and a `pai worker run` launched from inside one
 records `parent` in its status — so the forest is visible in `ps` (children
-indented under their parent, `├`/`└` connectors), the status line (`↳` under
-the parent) and each child gets its own follow pane. Handoffs travel **up
+indented under their parent, `├`/`└` connectors) and each child gets its own
+follow pane. Handoffs travel **up
 only**, from a child to its parent:
 
 ```
@@ -395,8 +395,8 @@ pai worker handoff '{"kind":"proposal","text":"run this on a cheap provider","da
 `result` is sent automatically when a child finishes). The handoff is appended
 to `<logDir>/<parent>.inbox.jsonl` (durable, ordered) and, when the parent is
 running, also delivered as an operator message `[handoff from <child id>]`. The
-parent sees it in its pane (`◆ from <id> · kind: text`, magenta), `ps` and the
-status line show `◆N` for an inbox with N handoffs, and `replay`/`follow`
+parent sees it in its pane (`◆ from <id> · kind: text`, magenta), `ps` shows
+`◆N` for an inbox with N handoffs, and `replay`/`follow`
 merge them into the transcript by timestamp. There is no sideways channel:
 siblings never see each other, everything goes up.
 
@@ -468,9 +468,9 @@ drive the desktop until it is handed over.
 
 Status files carry `contextTokens` (input + cache read + cache creation +
 output of the last assistant turn) and `contextWindow` (from the init event,
-else the provider's `contextWindow`, else 200 000). The `ps` table and the
-status line show `ctx 84k/200k (42%)` once it passes 60 % — yellow past
-70 %, red past 85 % — and the pane's liveness line always shows it.
+else the provider's `contextWindow`, else 200 000). The `ps` table shows
+`ctx 84k/200k (42%)` once it passes 60 % — yellow past 70 %, red past
+85 % — and the pane's liveness line always shows it.
 
 ### MCP for workers
 
@@ -559,7 +559,25 @@ the CLI calls.
 
 ## Status line
 
-Line 4 of the statusline lists this session's running workers (provider,
-label, age, current tool, context meter past 60 %) plus today's ✓/✗ tally.
-It prefers the standalone `~/.claude/worker-status-line.mjs` (plain node,
-built by `bun run build`) and falls back to `pai worker status-line`.
+Line 4 of the statusline is the worker bar: the provider and running-worker
+count, one row per running spawned worker, and today's ✓/✗ tally. It prefers
+the standalone `~/.claude/worker-status-line.mjs` (plain node, built by
+`bun run build`) and falls back to `pai worker status-line`.
+
+Example: `glm ▶2 | fix black buttons · 6m · grep … | spotcheck login · 1m · Edit: button.ts   ✓75 ✗4 today`
+
+Segment by segment:
+
+- provider tag (`glm`) — the chat pane's provider; `workers` when there is no tracked chat pane and the running workers are mixed
+- `▶2` — this terminal's running spawned workers: `state=running` **and** a live pid **and** not the chat pane; nothing at zero, so an idle terminal shows just `glm`
+- row `name · age · step` — the worker's `--label` (else the first 70 chars of the prompt, `unlabeled` when the run had neither), time since it started, and the verb of what it is doing; `#id` (the short form `pai worker ps` shows) joins the name only when two running workers share a label
+- step (`grep …`) — the current tool trimmed to its verb: no `Bash:` prefix, no flags, no quotes, ≤24 chars; file tools keep their `Edit: button.ts` shape
+- `✓75 ✗4 today` — today's finished workers: done vs failed
+
+The chat pane itself contributes only its provider — its age, state and
+inbox live in `pai worker ps`, never in the bar. Rows are flat and
+oldest-first; the worker forest (`↳` depth) and `◆N` inbox marks are `ps`
+territory too. A status file from before the `origin` flag (a running entry
+with no origin, the unlabeled placeholder and zero turns) is treated as the
+chat pane so it does not render as a phantom worker — that shim goes away
+once every pane runs code that writes `origin`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekmidian/pai",
-  "version": "0.39.1",
+  "version": "0.40.0",
   "description": "PAI Knowledge OS — Personal AI Infrastructure with federated memory and project management",
   "type": "module",
   "main": "dist/index.mjs",

package/scripts/build-hooks.mjs

@@ -29,6 +29,7 @@ import {
 } from "fs";
 import { join, resolve, basename } from "path";
 import { homedir, platform } from "os";
+import { isInsideWorkerWorktree } from "./lib/sync-guard.mjs";
 
 const HOOKS_SRC = "src/hooks/ts";
 const HOOKS_OUT = "dist/hooks";
@@ -143,7 +144,11 @@ console.log(
 // --sync: Symlink (or copy on Windows) all deployable files to ~/.claude/
 // ---------------------------------------------------------------------------
 
-if (doSync) {
+if (doSync && isInsideWorkerWorktree(process.cwd())) {
+  // Never repoint the live ~/.claude symlinks at a worktree that `pai worker
+  // merge` will delete — see scripts/lib/sync-guard.mjs.
+  console.log("✔ Hook symlinks skipped: build runs inside a worker worktree");
+} else if (doSync) {
   const useSymlinks = platform() !== "win32";
   const claudeDir = join(homedir(), ".claude");
   const hooksTarget = join(claudeDir, "Hooks");

package/scripts/build-skill-stubs.mjs

@@ -32,6 +32,7 @@ import {
 } from "fs";
 import { join, resolve } from "path";
 import { homedir, platform } from "os";
+import { isInsideWorkerWorktree } from "./lib/sync-guard.mjs";
 
 const PROMPTS_DIR = "src/daemon-mcp/prompts";
 const CUSTOM_DIR = join(PROMPTS_DIR, "custom");
@@ -107,13 +108,21 @@ function syncSymlinks(generatedNames) {
     const source = resolve(join(STUBS_OUT, name));
     const target = join(skillsDir, name);
 
+    // lstat once: dangling links must count as symlinks (existsSync misses them)
+    let entry;
+    try {
+      entry = lstatSync(target);
+    } catch {
+      // absent — fresh install
+    }
+
     // Never overwrite non-symlink directories (user's own skills)
-    if (existsSync(target) && !lstatSync(target).isSymbolicLink()) {
+    if (entry && !entry.isSymbolicLink()) {
       continue;
     }
 
-    // Check existing symlink
-    if (existsSync(target) && lstatSync(target).isSymbolicLink()) {
+    // Check existing symlink (may be dangling)
+    if (entry) {
       if (resolve(readlinkSync(target)) === source) {
         current++;
         continue;
@@ -197,6 +206,10 @@ for (const [fileName, dir] of [
 const customLabel = customNames.length > 0 ? ` (${builtinNames.length} built-in + ${customNames.length} custom)` : "";
 console.log(`✔ ${generated} skill stubs generated in ${STUBS_OUT}/${customLabel}`);
 
-if (doSync) {
+if (doSync && isInsideWorkerWorktree(process.cwd())) {
+  // Never repoint the live ~/.claude/skills symlinks at a worktree that
+  // `pai worker merge` will delete — see scripts/lib/sync-guard.mjs.
+  console.log("✔ Skill symlinks skipped: build runs inside a worker worktree");
+} else if (doSync) {
   syncSymlinks(generatedDirNames);
 }