@cognisphere-sh/cognisphere-harness 0.12.0 → 0.13.0

package/dist-web/index.html

@@ -16,7 +16,7 @@
         } catch (_) {}
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-1Hg12QW0.js"></script>
+    <script type="module" crossorigin src="/assets/index-CDE-jsH8.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/react-BIlrhC09.js">
     <link rel="modulepreload" crossorigin href="/assets/radix-DHW5y7jr.js">
     <link rel="modulepreload" crossorigin href="/assets/markdown-sumxz7Eq.js">

package/home-template/config.example

@@ -44,12 +44,6 @@ BACKUP_S3_ACCESS_KEY=    # keys for that endpoint (blank = aws CLI chain / IAM r
 BACKUP_S3_SECRET_KEY=
 AWS_PROFILE=             # local testing only: named aws-cli profile (EC2 uses the IAM role)
 
-# Token for the private @cognisphere-sh/* packages on GitHub Packages.
-# Leave blank to use the run user's `gh` CLI token (it must have the
-# `read:packages` scope: gh auth refresh -s read:packages). Or paste a
-# GitHub PAT with read:packages here for a non-interactive box.
-COGNISPHERE_NPM_TOKEN=
-
 # ---- deployment-specific params ---------------------------------------------
 # This file is harness-owned (refreshed on upgrade). Your app's extra keys go
 # in `config` too, but document them in scripts/app/config.example and read

package/home-template/docs/base-harness/README.md

@@ -95,8 +95,9 @@ plus an optional `X-App-User` header (see `app/README.md`).
   agent (`agent/` scope is yours; `<plugin-id>/` scopes are seeded by
   plugins and overwritten on every start).
 - `bootstrap/bootstrap.sh` — runs on every agent start; provisions the
-  agent's `.venv`, system deps, and the pinned `pi` version (installs or
-  upgrades/downgrades the global `pi` to match; override with `PI_VERSION`).
+  agent's `.venv`, system deps and `agent-browser`. Pi itself isn't installed
+  here: the harness runs the `pi` bundled with its own package, at the version
+  it was tested with.
 
 A **thread** is one conversation. `threadIdStrategy` controls how inbound
 messages map to threads (one global thread, one per plugin, or one per
@@ -142,8 +143,14 @@ Both under `harness/.secrets/` (0600, gitignored, editable via the console):
 - `secrets.json` — per-agent buckets: `agent` (agent-level env) plus one per
   plugin id. All keys are injected into the agent's environment.
 - `models.json` — per-provider credentials + the allowlist of enabled model
-  ids. Subscription OAuth logins (Claude Pro/Max, Codex) are connected from
-  the console's Models page instead of pasting keys.
+  ids. Subscription OAuth logins (Claude Pro/Max, Sign in with ChatGPT on
+  OpenAI, and the legacy OpenAI Codex) are connected from
+  the console's Models page instead of pasting keys. Their tokens live in
+  `.secrets/pi/` (this harness's own Pi config folder, not `~/.pi/agent`).
+  A model is usable when
+  its provider has its keys or a connected sign-in and the model is enabled.
+  A thread's own model (set from the chat header) that stops being usable
+  falls back to the agent's model until it is usable again.
 - `gws/` — Google sign-in for agents with the **gws** plugin. The shared
   "Web application" OAuth client (from your GCP project, with
   `<console origin>/api/gws/oauth/callback` as a redirect URI) is saved

package/home-template/scripts/build.sh

@@ -13,11 +13,6 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 [[ -f "$ROOT/config" ]] && source "$ROOT/config"
 
-# @cognisphere-sh/* need a read:packages token even though they're public.
-# ~/.npmrc references ${COGNISPHERE_NPM_TOKEN} (written by setup-server.sh);
-# export it from config, falling back to the gh CLI token.
-export COGNISPHERE_NPM_TOKEN="${COGNISPHERE_NPM_TOKEN:-$(gh auth token 2>/dev/null || true)}"
-
 cd "$ROOT"
 pnpm install --frozen-lockfile
 if [[ -f "$ROOT/app/package.json" ]]; then

package/home-template/scripts/lib/remote-bootstrap.sh

@@ -58,12 +58,8 @@ command -v claude >/dev/null || curl -fsSL https://claude.ai/install.sh | bash
 grep -q '\.local/bin' ~/.bashrc || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
 export PATH="$HOME/.local/bin:$PATH"
 
-# gh interactive auth — read:packages is required to install @cognisphere-sh packages
-if ! gh auth status >/dev/null 2>&1; then
-  gh auth login -s read:packages
-elif ! gh auth status 2>&1 | grep -q read:packages; then
-  gh auth refresh -s read:packages
-fi
+# gh interactive auth — used to clone the repo below
+gh auth status >/dev/null 2>&1 || gh auth login
 
 # Claude Code auth only — setup-token runs the OAuth flow and stores the
 # credential without starting a session. Skipped if already authenticated.

package/home-template/scripts/setup-server.sh

@@ -50,33 +50,7 @@ npm install -g corepack@latest
 corepack enable
 corepack prepare pnpm@latest --activate
 
-# ---- GitHub Packages token --------------------------------------------------
-# @cognisphere-sh/* live on GitHub Packages, whose npm registry requires a token
-# with the read:packages scope EVEN for public packages (anonymous = 401, a
-# scope-short token = 403). Prefer COGNISPHERE_NPM_TOKEN from config (a PAT); else
-# use the run user's gh CLI token. A gh OAuth token (gho_*) exists but often lacks
-# read:packages, so a bare `gh auth token` check would pass yet still 403 at fetch
-# time — verify/repair the scope here instead of failing mid-build.
-if [[ -z "${COGNISPHERE_NPM_TOKEN:-}" ]]; then
-  command -v gh >/dev/null || { echo "no COGNISPHERE_NPM_TOKEN in config and gh CLI not installed. Set COGNISPHERE_NPM_TOKEN (a PAT with read:packages) in config, or install gh and run: sudo -u $RUN_USER gh auth login -s read:packages"; exit 1; }
-  # gh runs as the app user; ensure it's logged in and the token carries read:packages.
-  # (gh prints "Token scopes:" to stderr, hence 2>&1.)
-  if ! sudo -u "$RUN_USER" gh auth status >/dev/null 2>&1; then
-    echo ">> gh is not authenticated for $RUN_USER — launching login (needs read:packages)"
-    sudo -u "$RUN_USER" gh auth login -s read:packages || { echo "gh auth login failed"; exit 1; }
-  elif ! sudo -u "$RUN_USER" gh auth status 2>&1 | grep -q 'read:packages'; then
-    echo ">> gh token for $RUN_USER lacks the read:packages scope — refreshing"
-    sudo -u "$RUN_USER" gh auth refresh -s read:packages || { echo "gh auth refresh failed"; exit 1; }
-  fi
-  COGNISPHERE_NPM_TOKEN="$(sudo -u "$RUN_USER" gh auth token 2>/dev/null || true)"
-fi
-[[ -n "$COGNISPHERE_NPM_TOKEN" ]] || { echo "no GitHub token for @cognisphere-sh packages. Set COGNISPHERE_NPM_TOKEN in config (a PAT with read:packages), or run: sudo -u $RUN_USER gh auth refresh -s read:packages"; exit 1; }
-# pnpm refuses to expand env-var credentials from the committed project .npmrc,
-# so the auth line must live in the run user's ~/.npmrc (a trusted source).
 RUN_HOME="$(getent passwd "$RUN_USER" | cut -d: -f6)"
-sudo -u "$RUN_USER" touch "$RUN_HOME/.npmrc"
-sudo -u "$RUN_USER" grep -qF 'npm.pkg.github.com/:_authToken' "$RUN_HOME/.npmrc" \
-  || echo '//npm.pkg.github.com/:_authToken=${COGNISPHERE_NPM_TOKEN}' | sudo -u "$RUN_USER" tee -a "$RUN_HOME/.npmrc" >/dev/null
 
 # ---- credentials ------------------------------------------------------------
 # `scripts/server.sh secrets` is the single source: it writes users.json
@@ -89,12 +63,13 @@ sudo -u "$RUN_USER" bash "$ROOT/scripts/server.sh" secrets
 # ---- build (as the app user so node_modules aren't root-owned) -------------
 # Delegated to scripts/build.sh — the same command used for every later deploy
 # (git pull && sudo ./scripts/server.sh restart).
-sudo -u "$RUN_USER" env COGNISPHERE_NPM_TOKEN="$COGNISPHERE_NPM_TOKEN" bash "$ROOT/scripts/build.sh"
+sudo -u "$RUN_USER" bash "$ROOT/scripts/build.sh"
 
 # ---- agent runtimes: build each agent's Python venv + CLIs ------------------
 # Each agent has a bootstrap/bootstrap.sh (idempotent) that creates <agent>/.venv
-# with markitdown/ddgs and installs the pi / agent-browser CLIs the harness
-# spawns by name. Run as the app user so the venv and ~/.local installs aren't
+# with markitdown/ddgs and installs the agent-browser CLI agents call by name.
+# (The harness runs the `pi` bundled with its own dependencies, not a global
+# one.) Run as the app user so the venv and ~/.local installs aren't
 # root-owned. Best-effort: a warning here shouldn't abort the whole provision.
 for bs in "$ROOT"/harness/agents/*/bootstrap/bootstrap.sh; do
   [[ -f "$bs" ]] || continue
@@ -114,13 +89,11 @@ NODE_BIN_DIR="$(dirname "$(command -v node)")"
 # $NODE_BIN_DIR/pnpm.
 PNPM_BIN="$(command -v pnpm)"
 PNPM_BIN_DIR="$(dirname "$PNPM_BIN")"
-# The harness spawns the `pi` coding agent by name (PATH lookup). pi is a
-# per-user install ($RUN_HOME/.local/bin/pi), so that dir MUST be on the unit
-# PATH or every spawn fails with `spawn pi ENOENT`. node/pnpm may both live in
+# $RUN_HOME/.local/bin holds per-user tool installs; node/pnpm may both live in
 # /usr/bin, so don't rely on their dirs to carry it.
 # $RUN_HOME/.npm-global/bin carries the npm-global CLIs the agent bootstrap
-# installs as the app user (pi, agent-browser) when the default npm prefix is
-# root-owned. Must be on the unit PATH or bare `agent-browser`/`pi` spawns 127.
+# installs as the app user (agent-browser) when the default npm prefix is
+# root-owned. Must be on the unit PATH or bare `agent-browser` spawns 127.
 UNIT_PATH="$RUN_HOME/.local/bin:$RUN_HOME/.npm-global/bin:$PNPM_BIN_DIR:$NODE_BIN_DIR:/usr/bin:/bin"
 
 # Renaming APP_NAME leaves the old name's units/nginx site/cron behind — clean those up by hand.
@@ -134,10 +107,6 @@ Type=simple
 User=$RUN_USER
 WorkingDirectory=$ROOT/harness
 Environment=PATH=$UNIT_PATH
-# Empty so pnpm can expand the \${COGNISPHERE_NPM_TOKEN} ref in the run user's
-# ~/.npmrc without warning. The service does no installs, so no real token is
-# needed at runtime.
-Environment=COGNISPHERE_NPM_TOKEN=
 ExecStart=$PNPM_BIN exec cognisphere serve --port $HARNESS_PORT
 Restart=on-failure
 RestartSec=3
@@ -162,7 +131,6 @@ Environment=PATH=$UNIT_PATH
 Environment=NODE_ENV=production
 Environment=PORT=$APP_PORT
 Environment=HARNESS_URL=http://127.0.0.1:$HARNESS_PORT
-Environment=COGNISPHERE_NPM_TOKEN=
 # 'next start' honors \$PORT; passing "-- -p" trips Next 16's arg parser (it
 # reads -p as a project dir), so rely on the PORT env above.
 ExecStart=$PNPM_BIN start

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@cognisphere-sh/cognisphere-harness",
-  "version": "0.12.0",
+  "version": "0.13.0",
+  "license": "MIT",
   "type": "module",
   "repository": {
     "type": "git",
@@ -16,17 +17,18 @@
     "home-template",
     "dist-web",
     "skills",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "LICENSE"
   ],
   "engines": {
-    "node": ">=20.12"
+    "node": ">=22.19.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "^0.84.4",
-    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-ai": "0.99.2",
+    "@earendil-works/pi-coding-agent": "0.99.2",
     "@hono/node-server": "^1.13.7",
     "ajv": "^8.17.1",
     "better-sqlite3": "^11.7.0",

package/skills/cognisphere-upgrade/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 # CogniSphere Upgrade
 
-Drive the **two-phase upgrade** (see `docs/distribution-and-deployment.md` §9):
+Drive the **two-phase upgrade** (see `docs/low-level/cli.md#upgrades`):
 
 1. **Code** — bump the installed dependency (`pnpm`/the CLI does this).
 2. **Data** — *this skill*: edit the harness dir (agents, plugins, secrets) to

package/skills/create-plugin/SKILL.md

@@ -204,8 +204,8 @@ Config/secret edits need an agent restart to take effect:
 
 ## Reference
 
-- Full lifecycle + on-disk layout: `docs/server.md` §4.9.3 and §5 (in this
-  repo, or bundled with the installed package).
+- Plugin lifecycle: `docs/low-level/plugins.md#discovery-and-lifecycle`; on-disk layout:
+  `docs/low-level/agents.md#persistent-layout` (repository references).
 - Builtin plugins are the best examples: `telegram` (long-poll + CLI +
   multi-kind `EventType`), `gws` (poller + shared lib in seed),
   `scheduler` (cron + CLI), `agent-messaging` (webhook inbox with

package/src/agents/base-agent/bootstrap/bootstrap.sh

@@ -102,7 +102,7 @@ python -m pip install -r bootstrap/requirements.txt
 # ── npm global prefix: make it user-writable ──────────────────────────
 # The default npm prefix may be a root-owned dir (e.g. /usr), so `npm install
 # -g` fails with EACCES when bootstrap runs as the (non-root) app user. Point
-# it at ~/.npm-global — where the pi/agent-browser wrappers already look — and
+# it at ~/.npm-global — where the agent-browser wrapper already looks — and
 # put its bin dir on PATH for the rest of this script and this shell.
 if command -v npm >/dev/null 2>&1; then
   export NPM_CONFIG_PREFIX="$HOME/.npm-global"
@@ -110,23 +110,7 @@ if command -v npm >/dev/null 2>&1; then
   export PATH="$NPM_CONFIG_PREFIX/bin:$PATH"
 fi
 
-# ── 3. pi-coding-agent (npm global) ───────────────────────────────────
-# Provides the `pi` binary that the harness runner spawns (`pi --mode rpc`).
-# Pinned to the version the harness was tested against — keep in sync with
-# `@earendil-works/pi-coding-agent` in packages/harness/package.json.
-PI_VERSION="${PI_VERSION:-0.84.4}"
-installed_pi="$(pi --version 2>/dev/null || true)"
-if [ "$installed_pi" = "$PI_VERSION" ]; then
-  log "pi-coding-agent $PI_VERSION already installed ($(command -v pi))"
-elif command -v npm >/dev/null 2>&1; then
-  log "installing @earendil-works/pi-coding-agent@$PI_VERSION via npm (found: ${installed_pi:-none})..."
-  npm install -g "@earendil-works/pi-coding-agent@$PI_VERSION" \
-    || warn "npm install -g @earendil-works/pi-coding-agent@$PI_VERSION failed"
-else
-  warn "npm not found; install Node.js (https://nodejs.org) and re-run, or install @earendil-works/pi-coding-agent@$PI_VERSION by hand"
-fi
-
-# ── 4. agent-browser (npm global) + its Chrome build ──────────────────
+# ── 3. agent-browser (npm global) + its Chrome build ──────────────────
 if command -v npm >/dev/null 2>&1; then
   if command -v agent-browser >/dev/null 2>&1; then
     log "agent-browser already installed ($(command -v agent-browser))"

package/src/agents/base-agent/extensions/context-meta.ts

@@ -171,7 +171,10 @@ export default function contextMeta(pi: ExtensionAPI): void {
 
     const last = event.messages[event.messages.length - 1];
     if (!last) return;
-    if (last.role === "user") {
+    // The last message is usually our own checkpoint (role "custom"): one is
+    // placed before every LLM call. Custom messages reach the model as user
+    // text, so the block goes there like on a plain user message.
+    if (last.role === "user" || last.role === "custom") {
       if (typeof last.content === "string") last.content = `${last.content}\n\n${block}`;
       else last.content.push({ type: "text", text: block });
     } else if (last.role === "toolResult") {

package/src/agents/base-agent/system_prompts/0-base_prompt.md

@@ -136,6 +136,7 @@ Timestamp: Fri 2026-04-17 14:30:05 IST
 Plugin: telegram
 Channel: 12345
 ThreadId: telegram-12345
+EventId: 42
 [IsSilent: true]
 [Retry: true]
 [Continuation: true]
@@ -154,6 +155,8 @@ ThreadId: telegram-12345
   so the result routes back here. It is a harness routing id — distinct from
   plugin-side ids like a Telegram chat id or Gmail thread id, which appear in
   the plugin-contributed fields.
+- **EventId** — the harness's id for this message, used to track its delivery.
+  You can ignore it.
 - **IsSilent: true** — appears only on silent messages (background updates).
   Do not act on a silent message alone; treat it as ambient context.
 - **Retry: true** — a previous delivery of _this_ message failed or was

package/src/api/agents.ts

@@ -18,7 +18,7 @@ import { agentDir, secretsRoot } from "../core/config.js";
 import type { ServerConfig } from "../core/config.js";
 import { ModelsStore } from "../core/models-store.js";
 import { findProviderInCatalog } from "../core/models-catalog.js";
-import { requiredCredentialsPresent } from "./credentials.js";
+import { modelUnavailableReason } from "../core/model-access.js";
 
 /**
  * /api/agents/* surface for the web UI.
@@ -284,18 +284,8 @@ export function agentsRouter(am: AgentManager, cfg: ServerConfig): Hono {
 
     const entry = findProviderInCatalog(provider);
     if (!entry) return c.json({ error: `unknown provider "${provider}"` }, 400);
-    const pcfg = models.getProvider(provider);
-    const configured =
-      !!pcfg && requiredCredentialsPresent(entry.credentials, pcfg.credentials);
-    if (!configured) {
-      return c.json({ error: `provider "${provider}" is not configured` }, 400);
-    }
-    if (!pcfg.enabledModels.includes(modelId)) {
-      return c.json(
-        { error: `model "${modelId}" is not enabled for ${provider}` },
-        400,
-      );
-    }
+    const unavailable = modelUnavailableReason(models, provider, modelId);
+    if (unavailable) return c.json({ error: unavailable }, 400);
     if (thinkingLevel !== null && !THINKING_LEVELS.has(thinkingLevel)) {
       return c.json({ error: "invalid thinkingLevel" }, 400);
     }

package/src/api/credentials.ts

@@ -1,5 +1,3 @@
-import type { CredField } from "../core/types.js";
-
 /**
  * Shared credential masking/merge helpers for /api/models and /api/secrets.
  *
@@ -27,16 +25,3 @@ export function applyMaskedPut(
     // unchanged — keep existing value
   } else if (typeof v === "string") target[key] = v;
 }
-
-/** Every required credential field has a non-empty stored value. */
-export function requiredCredentialsPresent(
-  fields: CredField[],
-  stored: Record<string, string>,
-): boolean {
-  return fields
-    .filter((f) => f.required)
-    .every((f) => {
-      const v = stored[f.key];
-      return typeof v === "string" && v.length > 0;
-    });
-}

package/src/api/models.ts

@@ -6,6 +6,7 @@ import type { ServerConfig } from "../core/config.js";
 import { secretsRoot } from "../core/config.js";
 import type { Logger } from "../core/logger.js";
 import { PROVIDER_CATALOG } from "../core/models-catalog.js";
+import { providerAuthenticated } from "../core/model-access.js";
 import { ModelsStore } from "../core/models-store.js";
 import { OAuthLoginManager } from "../core/oauth-logins.js";
 import { syncPiModelOverrides } from "../core/pi-models-sync.js";
@@ -14,7 +15,6 @@ import {
   applyMaskedPut,
   MASK,
   maskCredential,
-  requiredCredentialsPresent,
 } from "./credentials.js";
 
 /**
@@ -124,16 +124,10 @@ export function modelsRouter(
       for (const field of entry.credentials) {
         values[field.key] = maskCredential(stored[field.key], field.secret);
       }
-      const requiredOk = requiredCredentialsPresent(entry.credentials, stored);
       const oauthConnected =
         entry.oauth === true &&
         readStoredCredential(entry.id)?.type === "oauth";
-      // OAuth-only providers (no cred fields) are configured iff connected;
-      // otherwise OAuth connection satisfies missing required fields.
-      const configured =
-        entry.credentials.length === 0
-          ? oauthConnected
-          : requiredOk || oauthConnected;
+      const configured = providerAuthenticated(entry, stored);
       return {
         id: entry.id,
         displayName: entry.displayName,

package/src/api/secrets.ts

@@ -26,9 +26,9 @@ import { applyMaskedPut, MASK, maskCredential } from "./credentials.js";
  *   secrets[agentId][bucketId][KEY] = maskedString
  *   schemas[agentId][bucketId]     = JsonSchema
  *
- * v0 stores plaintext on disk (HLD §15). Runtime exposes resolved values
- * to the pi child as env vars on every spawn, so a value change requires
- * a server restart to take effect — the UI surfaces this caveat.
+ * Stores plaintext on disk and exposes resolved values to pi as env vars.
+ * PUT invalidates the cache and requests a soft reload of affected agents;
+ * active batches drain before replacement runners use the new values.
  */
 
 type Bucket = Record<string, string>;

package/src/cli/index.ts

@@ -1,6 +1,6 @@
 /**
  * `cognisphere` CLI entrypoint — install, scaffold, run, and upgrade a harness
- * (see docs/distribution-and-deployment.md §10). Dispatch only; each command
+ * (see docs/low-level/cli.md#cli). Dispatch only; each command
  * lives in its own module.
  */
 import { cmdAgentNew } from "./agent.js";

package/src/cli/init.ts

@@ -35,14 +35,6 @@ config
 **/inboxes/
 `;
 
-// The auth token deliberately is NOT here: pnpm refuses to expand env-var
-// credentials from a committed project .npmrc, so the _authToken line must
-// live in the run user's ~/.npmrc (scripts/setup-server.sh writes it on the
-// server; `init` prints the one-liner for local installs).
-const NPMRC = `# @cognisphere-sh/* packages live on GitHub Packages, not npmjs.org.
-@cognisphere-sh:registry=https://npm.pkg.github.com
-`;
-
 const WORKSPACE_YAML = `packages:
   - harness
   - app
@@ -79,7 +71,6 @@ export function cmdInit(argv: string[]): void {
     description: `${id}: cognisphere app home — the agent harness (harness/) + the user-facing app (app/). Workspace members are listed in pnpm-workspace.yaml.`,
   });
   writeFileSync(join(dir, "pnpm-workspace.yaml"), WORKSPACE_YAML);
-  writeFileSync(join(dir, ".npmrc"), NPMRC);
   writeFileSync(join(dir, ".gitignore"), GITIGNORE);
 
   // Deploy scripts, config templates, and the app/ placeholder — shipped with
@@ -148,9 +139,6 @@ export function cmdInit(argv: string[]): void {
   info("");
   info("Next steps:");
   info(`  cd ${cdTarget}`);
-  info("  # the private registry needs a read:packages token in YOUR ~/.npmrc");
-  info("  # (same env var the deploy scripts use — export it before installing):");
-  info("  echo '//npm.pkg.github.com/:_authToken=${COGNISPHERE_NPM_TOKEN}' >> ~/.npmrc");
   info("  pnpm install");
   info("  cd harness");
   info("  pnpm exec cognisphere agent new <name>           # add your first agent");

package/src/core/agent-manager.ts

@@ -1,7 +1,6 @@
 import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { join } from "node:path";
-import { readStoredCredential } from "@earendil-works/pi-coding-agent";
 import { Ajv, type ErrorObject } from "ajv";
 import type { ServerConfig } from "./config.js";
 import { agentDir, agentsRoot, secretsRoot } from "./config.js";
@@ -12,6 +11,7 @@ import { CORE_PLUGIN_IDS } from "./plugin-registry.js";
 import { AgentDb } from "./queue.js";
 import { AgentRunner } from "./runner.js";
 import { findProviderInCatalog } from "./models-catalog.js";
+import { modelUnavailableReason } from "./model-access.js";
 import { ModelsStore } from "./models-store.js";
 import { syncPiModelOverrides } from "./pi-models-sync.js";
 import { AGENT_BUCKET, SecretsStore } from "./secrets.js";
@@ -70,10 +70,9 @@ export class LifecycleError extends Error {
 }
 
 /**
- * Loads agents from disk on boot and exposes them by id. Authoring (creating
- * agents, installing plugins, editing configs) is deferred to a later phase
- * — see `docs/v0-deferred.md`. v0: agents are created manually on disk; the
- * server picks them up at boot.
+ * Loads agents from disk on boot and exposes them by id. The CLI scaffolds
+ * agent directories; the server discovers them at boot. Settings APIs reload
+ * existing agents and plugins. See docs/low-level/core.md for operating procedures.
  *
  * Lifecycle:
  *   - boot()                   → load every agent dir; failed agents stay listed.
@@ -491,6 +490,8 @@ export class AgentManager {
       envSecrets,
       resolveProviderEnv: (providerId) =>
         resolveProviderEnv(this.models, providerId, dir, this.log),
+      modelUnavailableReason: (providerId, modelId) =>
+        modelUnavailableReason(this.models, providerId, modelId),
       log: childLogger(`agent:${inst.id}`),
     });
     // When a stale-reload is pending and the last active batch finishes,
@@ -770,10 +771,10 @@ const VERTEX_SA_FILE = ".vertex-sa.json";
 
 /**
  * Validate the agent's chosen provider/model against operator settings and
- * return the env vars pi should see. Throws if the provider isn't configured,
- * the model isn't enabled, or required credentials are missing — but only
- * when a model id is specified; an agent.json with provider but no model
- * passes through silently (preserves the pre-merge permissive behavior).
+ * return the env vars pi should see. Throws with the shared
+ * `modelUnavailableReason()` when the model can't be used — but only when a
+ * model id is specified; an agent.json with provider but no model passes
+ * through silently (preserves the pre-merge permissive behavior).
  *
  * Special case: google-vertex's `serviceAccountKey` field is paste-blob
  * JSON — we write it to <agentDir>/.vertex-sa.json (0600) and point
@@ -793,47 +794,11 @@ function resolveAndValidateProvider(
 ): Record<string, string> {
   const providerId = agentJson.model?.provider;
   if (!providerId) return {};
-  const entry = findProviderInCatalog(providerId);
-  if (!entry) return {};
-  // Subscription OAuth (tokens in pi's own auth.json) substitutes for
-  // models.json credentials — pi children resolve auth.json themselves,
-  // so nothing extra is injected; only the model allowlist still applies.
-  const oauthConnected =
-    entry.oauth === true && readStoredCredential(providerId)?.type === "oauth";
-  const cfg =
-    models.getProvider(providerId) ??
-    (oauthConnected ? { credentials: {}, enabledModels: [] } : undefined);
   const modelId = agentJson.model?.id;
-
-  if (!cfg) {
-    if (modelId) {
-      throw new Error(
-        `agent ${agentId}: provider ${providerId} is not configured in Models settings`,
-      );
-    }
-    return {};
-  }
-
   if (modelId) {
-    if (cfg.enabledModels.length === 0 || !cfg.enabledModels.includes(modelId)) {
-      throw new Error(
-        `agent ${agentId}: model ${providerId}/${modelId} is not enabled in Models settings`,
-      );
-    }
-    const missing = entry.credentials
-      .filter((f) => f.required)
-      .filter((f) => {
-        const v = cfg.credentials[f.key];
-        return typeof v !== "string" || v.length === 0;
-      })
-      .map((f) => f.label);
-    if (missing.length > 0 && !oauthConnected) {
-      throw new Error(
-        `agent ${agentId}: provider ${providerId} is missing required credentials: ${missing.join(", ")} (set them in Models settings)`,
-      );
-    }
+    const reason = modelUnavailableReason(models, providerId, modelId);
+    if (reason) throw new Error(`agent ${agentId}: ${reason}`);
   }
-
   return resolveProviderEnv(models, providerId, agentDir, log);
 }
 

package/src/core/config.ts

@@ -67,6 +67,12 @@ export function secretsRoot(cfg: ServerConfig): string {
   return join(harnessRoot(cfg), ".secrets");
 }
 
+/** Pi's config folder for this harness (`PI_CODING_AGENT_DIR`). Under
+ *  `.secrets/` because its `auth.json` holds sign-in tokens. */
+export function piAgentDir(cfg: ServerConfig): string {
+  return join(secretsRoot(cfg), "pi");
+}
+
 /** Path of the harness-wide settings file (currently just `{ timezone }`). */
 export function harnessJsonFile(cfg: ServerConfig): string {
   return join(harnessRoot(cfg), "harness.json");

package/src/core/main.ts

@@ -2,7 +2,7 @@ import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { Hono } from "hono";
 import { randomUUID } from "node:crypto";
-import { existsSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -23,7 +23,7 @@ import { modelsRouter } from "../api/models.js";
 import { secretsRouter } from "../api/secrets.js";
 import { maybeHandleWebhook } from "../api/webhook.js";
 import { AgentManager } from "./agent-manager.js";
-import { loadConfig, userPluginsRoot } from "./config.js";
+import { loadConfig, piAgentDir, userPluginsRoot } from "./config.js";
 import { childLogger, rootLogger } from "./logger.js";
 import { PluginRegistry } from "./plugin-registry.js";
 
@@ -50,6 +50,14 @@ async function main(): Promise<void> {
   const log = rootLogger();
   log.info({ cfg }, "boot");
 
+  // Pi's config folder (auth.json sign-ins, models.json, settings.json,
+  // trust.json) is per harness, not the run user's global ~/.pi/agent, so
+  // harnesses and the operator's own `pi` never share or overwrite each
+  // other's settings. Pi reads the variable on every lookup; every pi child
+  // inherits it via `{...process.env}` (runner.spawnPi).
+  process.env.PI_CODING_AGENT_DIR = piAgentDir(cfg);
+  mkdirSync(piAgentDir(cfg), { recursive: true, mode: 0o700 });
+
   // Shared secret that authenticates in-harness callers of the agent-messaging
   // webhook. Generated per boot unless the operator pins one; inherited by
   // every pi child via `{...process.env}` (runner.spawnPi) so seeded scripts

package/src/core/model-access.ts

@@ -0,0 +1,55 @@
+import { readStoredCredential } from "@earendil-works/pi-coding-agent";
+import { findProviderInCatalog } from "./models-catalog.js";
+import type { ModelsStore } from "./models-store.js";
+import type { CredField, ProviderCatalogEntry } from "./types.js";
+
+/** Every required credential field has a non-empty stored value. */
+export function requiredCredentialsPresent(
+  fields: CredField[],
+  stored: Record<string, string>,
+): boolean {
+  return fields
+    .filter((f) => f.required)
+    .every((f) => {
+      const v = stored[f.key];
+      return typeof v === "string" && v.length > 0;
+    });
+}
+
+/**
+ * A provider can authenticate when its required credentials are stored or a
+ * subscription sign-in is connected (tokens live in pi's own auth.json).
+ * OAuth-only providers (no credential fields) need the sign-in.
+ */
+export function providerAuthenticated(
+  entry: ProviderCatalogEntry,
+  stored: Record<string, string>,
+): boolean {
+  const oauthConnected =
+    entry.oauth === true && readStoredCredential(entry.id)?.type === "oauth";
+  if (entry.credentials.length === 0) return oauthConnected;
+  return oauthConnected || requiredCredentialsPresent(entry.credentials, stored);
+}
+
+/**
+ * Why `providerId/modelId` can't be used right now, or null if it can. The one
+ * rule shared by agent startup, the thread-model endpoint and every batch
+ * spawn. Providers outside the catalog pass through: pi resolves them from the
+ * ambient environment.
+ */
+export function modelUnavailableReason(
+  models: ModelsStore,
+  providerId: string,
+  modelId: string,
+): string | null {
+  const entry = findProviderInCatalog(providerId);
+  if (!entry) return null;
+  const cfg = models.getProvider(providerId);
+  if (!providerAuthenticated(entry, cfg?.credentials ?? {})) {
+    return `provider ${providerId} has no credentials or sign-in in Models settings`;
+  }
+  if (!cfg?.enabledModels.includes(modelId)) {
+    return `model ${providerId}/${modelId} is not enabled in Models settings`;
+  }
+  return null;
+}