feat: complete evidence restructuring worktree

backend/src/pi/managed-config.ts

@@ -56,6 +56,34 @@ export function validateDeclarativePiConfig(raw: string): void {
   assertDeclarativePiConfig(parsePiConfigJson(raw));
 }
 
+/** Return the selected provider's declarative apiKey value without knowing provider IDs in code. */
+export function configuredPiProviderApiKey(
+  raw: string | undefined,
+  provider: string | undefined,
+): string | undefined {
+  if (raw === undefined || provider === undefined) return undefined;
+  const parsed = parsePiConfigJson(raw);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new PiManagedConfigError();
+  }
+  const providers = (parsed as { providers?: unknown }).providers;
+  if (!providers || typeof providers !== "object" || Array.isArray(providers)) {
+    throw new PiManagedConfigError();
+  }
+  const entry = Object.entries(providers as Record<string, unknown>)
+    .find(([id]) => id.trim().toLowerCase() === provider.trim().toLowerCase());
+  if (!entry) return undefined;
+  const config = entry[1];
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new PiManagedConfigError();
+  }
+  assertDeclarativePiConfig(config);
+  const apiKey = (config as { apiKey?: unknown }).apiKey;
+  if (apiKey === undefined) return undefined;
+  if (typeof apiKey !== "string" || apiKey.length === 0) throw new PiManagedConfigError();
+  return apiKey;
+}
+
 function configuredPiAgentDir(): string {
   return resolve(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"));
 }
@@ -102,6 +130,7 @@ export function readConfiguredPiAgentFile(
 export interface PiRuntimeAgentSnapshot {
   agentDir: string;
   sessionDir: string;
+  models?: string;
   cleanup: () => void;
 }
 
@@ -152,6 +181,7 @@ export function createPiRuntimeAgentSnapshot(): PiRuntimeAgentSnapshot {
   return {
     agentDir: snapshotDir,
     sessionDir: process.env.PI_CODING_AGENT_SESSION_DIR || join(sourceAgentDir, "sessions"),
+    models,
     cleanup: () => {
       if (cleaned) return;
       cleaned = true;

backend/src/pi/management.ts

@@ -9,8 +9,10 @@ import {
 } from "../settings/settings-store.js";
 import type { PiModel } from "./list-models.js";
 import {
+  configuredPiProviderApiKey,
   PI_MANAGED_CONFIG_ERROR_MESSAGE,
   isPiManagedConfigError,
+  readConfiguredPiAgentFile,
 } from "./managed-config.js";
 import { createPiProviderSmoke, type PiProviderSmoke } from "./provider-smoke.js";
 import { loadPiAuthProviders } from "./auth-providers.js";
@@ -119,6 +121,10 @@ export function createPiManagement(config: AppConfig, deps: PiManagementDeps): P
         authProviders: loadPiAuthProviders(),
         resolveCredentialValue: () => secretValue(config, "THT_MODEL_API_KEY"),
         credentialFile: config.modelApiKeyFile,
+        configuredApiKey: configuredPiProviderApiKey(
+          readConfiguredPiAgentFile("models.json", true),
+          provider,
+        ),
       });
     } catch {
       return "missing";

backend/src/pi/pi-process-manager.ts

@@ -7,7 +7,10 @@ import { buildPiChildEnv, canonicalPiProvider } from "./provider-credentials.js"
 import { loadPiAuthProviders } from "./auth-providers.js";
 import { secretValue } from "../config/secret-bundle.js";
 import { clearPrincipalEnvironment, principalEnvironment, type PrincipalContext } from "../auth/principal.js";
-import { createPiRuntimeAgentSnapshot } from "./managed-config.js";
+import {
+  configuredPiProviderApiKey,
+  createPiRuntimeAgentSnapshot,
+} from "./managed-config.js";
 
 export interface SessionRuntime {
   rpc: RpcClient;
@@ -81,6 +84,7 @@ export class PiProcessManager {
         authProviders: this.loadAuthProviders(agent.agentDir),
         credentialValue: secretValue(this.cfg, "THT_MODEL_API_KEY"),
         credentialFile: this.cfg.modelApiKeyFile,
+        configuredApiKey: configuredPiProviderApiKey(agent.models, provider),
         additions: { THT_SESSION: sessionId, THT_AUTHOR: author },
       });
       env.PI_CODING_AGENT_DIR = agent.agentDir;

backend/src/pi/provider-credentials.ts

@@ -42,9 +42,14 @@ const PROVIDER_KEY_ENV: Readonly<Record<string, string>> = {
 const COMPOUND_PROVIDERS = new Set([
   "amazon-bedrock", "azure-openai-responses", "cloudflare-ai-gateway", "cloudflare-workers-ai",
 ]);
-const LOCAL_PROVIDERS = new Set([
-  "ollama", "lmstudio", "local", "aritmolab", "local-qwen", "faux",
-]);
+
+function configuredCredentialEnv(apiKey: string | undefined): string | null | undefined {
+  if (apiKey === undefined) return undefined;
+  if (!apiKey.startsWith("$")) return null;
+  const matched = /^\$(?:\{([A-Z][A-Z0-9_]*(?:API_KEY|TOKEN))\}|([A-Z][A-Z0-9_]*(?:API_KEY|TOKEN)))$/.exec(apiKey);
+  if (!matched) throw new Error("model provider credential is unavailable");
+  return matched[1] ?? matched[2];
+}
 
 export function canonicalPiProvider(provider: string | undefined): string | undefined {
   const value = provider?.trim().toLowerCase();
@@ -106,6 +111,8 @@ export function buildPiChildEnv(opts: {
   credentialFile?: string;
   additions?: NodeJS.ProcessEnv;
   credentialValue?: string;
+  /** Exact apiKey declaration from the selected provider in models.json. */
+  configuredApiKey?: string;
   fsOps?: CredentialFsOps;
   /**
    * Providers pi can authenticate from its own auth store. For these, the single
@@ -147,17 +154,22 @@ export function buildPiChildEnv(opts: {
   delete env.THT_SSL_CA_FILE;
   for (const name of PI_0803_CREDENTIAL_ENV_NAMES) delete env[name];
   const provider = canonicalPiProvider(opts.provider);
+  const configuredEnv = configuredCredentialEnv(opts.configuredApiKey);
+  if (configuredEnv) delete env[configuredEnv];
   if (provider && COMPOUND_PROVIDERS.has(provider)) {
     throw new Error(
       "compound credential bundles are unsupported by THT_MODEL_API_KEY_FILE; "
       + "dedicated provider configuration is required",
     );
   }
-  if (provider && !LOCAL_PROVIDERS.has(provider)) {
+  if (provider) {
     // pi self-authenticates this provider from its own auth store; injecting the
     // single managed key here would force one provider's key onto another.
     if (opts.authProviders?.has(provider)) return env;
-    const envName = PROVIDER_KEY_ENV[provider];
+    // A literal apiKey is entirely owned by models.json (commonly a non-secret
+    // placeholder for a local OpenAI-compatible endpoint) and needs no managed key.
+    if (configuredEnv === null) return env;
+    const envName = configuredEnv ?? PROVIDER_KEY_ENV[provider];
     if (!envName || (!opts.credentialFile && opts.credentialValue === undefined)) {
       throw new Error("model provider credential is unavailable");
     }
@@ -169,7 +181,7 @@ export function buildPiChildEnv(opts: {
     }
     else if (opts.credentialFile) env[envName] = readCredential(opts.credentialFile, opts.fsOps ?? realFs);
     else throw new Error("model provider credential is unavailable");
-  } else if (opts.credentialFile && !provider) {
+  } else if (opts.credentialFile) {
     throw new Error("model provider credential is unavailable");
   }
   return env;
@@ -181,11 +193,14 @@ export function piProviderCredentialStatus(opts: {
   credentialFile?: string;
   resolveCredentialValue?: () => string | undefined;
   authProviders?: ReadonlySet<string>;
+  configuredApiKey?: string;
   fsOps?: CredentialFsOps;
 }): PiCredentialStatus {
   const provider = canonicalPiProvider(opts.provider);
-  if (!provider || LOCAL_PROVIDERS.has(provider)) return "missing";
+  if (!provider) return "missing";
   if (opts.authProviders?.has(provider)) return "present";
+  const configuredEnv = configuredCredentialEnv(opts.configuredApiKey);
+  if (configuredEnv === null) return "missing";
   try {
     buildPiChildEnv({
       ambient: {},
@@ -193,6 +208,7 @@ export function piProviderCredentialStatus(opts: {
       credentialFile: opts.credentialFile,
       credentialValue: opts.resolveCredentialValue?.(),
       authProviders: opts.authProviders,
+      configuredApiKey: opts.configuredApiKey,
       fsOps: opts.fsOps,
     });
     return "present";

backend/src/pi/provider-smoke.ts

@@ -11,6 +11,7 @@ import { buildPiChildEnv, canonicalPiProvider } from "./provider-credentials.js"
 import type { PiReasoning } from "./management.js";
 import {
   PiManagedConfigError,
+  configuredPiProviderApiKey,
   isPiManagedConfigError,
   parsePiConfigJson,
   readConfiguredPiAgentFile,
@@ -65,11 +66,15 @@ export function createPiProviderSmoke(
       const canonicalProvider = canonicalPiProvider(provider);
       if (!canonicalProvider || timeoutMs <= 0) throw providerFailure();
       const configuredAuthProviders = authProviders();
+      const configuredModels = options.readModelsStore
+        ? options.readModelsStore()
+        : readConfiguredPiAgentFile("models.json", true);
       const env = buildPiChildEnv({
         provider: canonicalProvider,
         authProviders: configuredAuthProviders,
         credentialValue: secretValue(config, "THT_MODEL_API_KEY"),
         credentialFile: config.modelApiKeyFile,
+        configuredApiKey: configuredPiProviderApiKey(configuredModels, canonicalProvider),
       });
       clearPrincipalEnvironment(env);
       delete env.THT_DATA_ROOT;
@@ -90,9 +95,6 @@ export function createPiProviderSmoke(
         );
         writeDeclarativeAgentConfig(join(isolatedAgentDir, "auth.json"), authStore);
       }
-      const configuredModels = options.readModelsStore
-        ? options.readModelsStore()
-        : readConfiguredPiAgentFile("models.json", true);
       if (configuredModels !== undefined) {
         const modelsStore = selectedProviderModelsStore(
           configuredModels,

backend/test/pi-managed-config.test.ts

@@ -0,0 +1,28 @@
+import { expect, test } from "vitest";
+import {
+  PI_MANAGED_CONFIG_ERROR_MESSAGE,
+  configuredPiProviderApiKey,
+} from "../src/pi/managed-config.js";
+
+test("provider credential declarations are selected from models.json by provider ID", () => {
+  const raw = JSON.stringify({
+    providers: {
+      hosted: { apiKey: "$HOSTED_API_KEY", models: [{ id: "one" }] },
+      local: { apiKey: "local", models: [{ id: "two" }] },
+    },
+  });
+
+  expect(configuredPiProviderApiKey(raw, "HOSTED")).toBe("$HOSTED_API_KEY");
+  expect(configuredPiProviderApiKey(raw, "local")).toBe("local");
+  expect(configuredPiProviderApiKey(raw, "missing")).toBeUndefined();
+});
+
+test.each([
+  JSON.stringify({ providers: [] }),
+  JSON.stringify({ providers: { local: "invalid" } }),
+  JSON.stringify({ providers: { local: { apiKey: 42 } } }),
+  JSON.stringify({ providers: { local: { apiKey: "!must-not-run" } } }),
+])("invalid declarative provider credential configuration fails closed", (raw) => {
+  expect(() => configuredPiProviderApiKey(raw, "local"))
+    .toThrow(PI_MANAGED_CONFIG_ERROR_MESSAGE);
+});

backend/test/pi-process-manager.test.ts

@@ -22,7 +22,7 @@ const SAFE_AUTH = '{"deepseek":{"type":"api_key","key":"safe-token"}}\n';
 const SAFE_MODELS = [
   "{",
   '  "providers": {',
-  '    "local-qwen": {"baseUrl":"http://model.invalid/v1","models":[{"id":"qwen"}]}',
+  '    "local-qwen": {"baseUrl":"http://model.invalid/v1","apiKey":"local","models":[{"id":"qwen"}]}',
   "  }",
   "}",
   "",
@@ -670,9 +670,22 @@ test.each([["OpenAI", "openai"], ["gemini", "google"]])(
   },
 );
 
-test.each(["ollama", "local-qwen"])(
-  "local provider %s spawns without a model key and scrubs ambient credentials",
+test.each(["installation-local", "private-compatible"])(
+  "provider %s configured with a literal apiKey spawns without a managed key",
   async (provider) => {
+    const root = mkdtempSync(path.join(tmpdir(), "tht-local-provider-"));
+    const agentDir = path.join(root, "agent");
+    mkdirSync(agentDir, { mode: 0o700 });
+    writeFileSync(path.join(agentDir, "models.json"), JSON.stringify({
+      providers: {
+        [provider]: {
+          baseUrl: "http://model.invalid/v1",
+          apiKey: "local",
+          models: [{ id: "model" }],
+        },
+      },
+    }), { mode: 0o600 });
+    vi.stubEnv("PI_CODING_AGENT_DIR", agentDir);
     vi.stubEnv("PI_PROVIDER_API_KEY", "ambient-secret");
     vi.stubEnv("THT_MODEL_API_KEY_FILE", "/ambient/secret-path");
     vi.stubEnv("OPENAI_API_KEY", "unselected-provider-secret");
@@ -690,6 +703,7 @@ test.each(["ollama", "local-qwen"])(
     } finally {
       mgr.teardown(`local-session-${provider}`);
       vi.unstubAllEnvs();
+      rmSync(root, { recursive: true, force: true });
     }
   },
 );

backend/test/provider-credentials.test.ts

@@ -117,20 +117,41 @@ test("single-key providers scrub ambient compound companions before injecting th
   expect(env).not.toHaveProperty("CLOUDFLARE_GATEWAY_ID");
 });
 
-test("local-qwen is an explicit local provider and needs no generic key", () => {
+test("a provider with a literal apiKey in models.json needs no code-level provider exception", () => {
   const env = buildPiChildEnv({
     ambient: {
       PI_PROVIDER_API_KEY: "must-not-leak",
       OPENAI_API_KEY: "must-not-leak",
       THT_MODEL_API_KEY_FILE: "/must/not/leak",
     },
-    provider: "local-qwen",
+    provider: "installation-local",
+    configuredApiKey: "local",
   });
   expect(env).not.toHaveProperty("PI_PROVIDER_API_KEY");
   expect(env).not.toHaveProperty("OPENAI_API_KEY");
   expect(env).not.toHaveProperty("THT_MODEL_API_KEY_FILE");
 });
 
+test.each(["$PRIVATE_PROVIDER_API_KEY", "${PRIVATE_PROVIDER_API_KEY}"])(
+  "a custom provider credential target is derived from models.json: %s",
+  (configuredApiKey) => {
+    const env = buildPiChildEnv({
+      ambient: { PRIVATE_PROVIDER_API_KEY: "stale" },
+      provider: "private-provider",
+      configuredApiKey,
+      credentialValue: "selected-secret",
+    });
+    expect(env.PRIVATE_PROVIDER_API_KEY).toBe("selected-secret");
+  },
+);
+
+test("a custom provider cannot redirect a managed credential into a process-control variable", () => {
+  expect(() => buildPiChildEnv({
+    ambient: {}, provider: "private-provider", configuredApiKey: "$PATH",
+    credentialValue: "selected-secret",
+  })).toThrow("model provider credential is unavailable");
+});
+
 test("credential status reports only present or missing without treating local providers as credentialed", () => {
   expect(piProviderCredentialStatus({
     provider: "deepseek",
@@ -139,7 +160,8 @@ test("credential status reports only present or missing without treating local p
   })).toBe("present");
   expect(piProviderCredentialStatus({ provider: "deepseek" })).toBe("missing");
   expect(piProviderCredentialStatus({
-    provider: "local-qwen",
+    provider: "installation-local",
+    configuredApiKey: "local",
     resolveCredentialValue: () => "must-not-be-returned",
   })).toBe("missing");
 });
@@ -159,7 +181,8 @@ test("credential status never resolves the generic secret for auth-store or loca
     resolveCredentialValue: unreadableSecret,
   })).toBe("present");
   expect(piProviderCredentialStatus({
-    provider: "local-qwen",
+    provider: "installation-local",
+    configuredApiKey: "local",
     resolveCredentialValue: unreadableSecret,
   })).toBe("missing");
   expect(secretReads).toBe(0);