@herbertgao/pi-extensions 2026.9.13 → 2026.9.15

package/node_modules/pi-mcp-adapter/jev-key-store.ts

@@ -1,20 +1,44 @@
 import { createSecureKeyringStore, type SecureKeyringStore } from "./secure-keyring.ts";
 
+/** The Jev decisions endpoint used when `SYSTEMONE_ENDPOINT` is not set. */
+export const JEV_DEFAULT_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
+const SYSTEMONE_ENDPOINT_ENV = "SYSTEMONE_ENDPOINT";
+const SYSTEMONE_API_KEY_ENV = "SYSTEMONE_API_KEY";
+/** TypeSafe-issued key: honored only for the default endpoint and never sent anywhere else. */
+const LEGACY_TYPESAFE_API_KEY_ENV = "TYPESAFE_API_KEY";
+/** Origin recorded in version 1 credential records. */
 export const TYPESAFE_API_ORIGIN = "https://api.typesafe.ai";
-export const JEV_KEYRING_SERVICE = "pi-mcp-adapter.service-key";
+/** Version 1 credential account, still read for the default endpoint. */
 export const JEV_KEYRING_ACCOUNT = "typesafe@sha256(https://api.typesafe.ai)";
+export const JEV_KEYRING_SERVICE = "pi-mcp-adapter.service-key";
+
+const MAX_ENDPOINT_LENGTH = 512;
+/** The path `@typesafe-ai/sdk` appends to whatever base URL it is given. */
+export const JEV_SDK_PATH = "/v1/systemone";
+
+export interface ResolvedJevEndpoint {
+  /** Canonical absolute URL sent to the provider, for example `https://opencode.ai/zen/v1/systemone`. */
+  readonly href: string;
+  /** URL origin, used as the SDK base URL. */
+  readonly origin: string;
+  /** URL path, rewritten onto the SDK's fixed path by the pinned fetch. */
+  readonly path: string;
+}
+
+export type JevEndpointResolution =
+  | { status: "resolved"; source: "environment" | "default"; endpoint: ResolvedJevEndpoint }
+  | { status: "unavailable"; message: string };
 
 interface StoredJevKey {
-  version: 1;
-  provider: "typesafe";
-  origin: typeof TYPESAFE_API_ORIGIN;
+  version: 2;
+  endpoint: string;
   apiKey: string;
 }
 
 export class JevCredentialStoreError extends Error {
   readonly code = "JEV_CREDENTIAL_STORE_UNAVAILABLE";
   constructor(readonly operation: "read" | "write" | "remove", cause: unknown) {
-    super(`TypeSafe API key secure credential store unavailable during ${operation}. Configure or unlock the OS credential store and retry.`, { cause });
+    super(`Jev API key secure credential store unavailable during ${operation}. Configure or unlock the OS credential store and retry.`, { cause });
     this.name = "JevCredentialStoreError";
   }
 }
@@ -26,54 +50,143 @@ export type JevCredentialResolution =
 
 function validateApiKey(value: unknown): string {
   if (typeof value !== "string" || value.trim().length === 0 || /[\u0000-\u001f\u007f]/.test(value)) {
-    throw new Error("TypeSafe API key must be a non-empty string without control characters");
+    throw new Error("Jev API key must be a non-empty string without control characters");
   }
   return value;
 }
 
+/**
+ * Constrains the operator-supplied endpoint to an absolute HTTPS URL without credentials, query, or fragment, so
+ * the pinned fetch can match it exactly and a stray value cannot redirect requests or smuggle a query string.
+ */
+function parseEndpoint(raw: string, label: string): ResolvedJevEndpoint {
+  if (typeof raw !== "string" || raw.trim().length === 0) throw new Error(`${label} must be a non-empty URL`);
+  if (raw.length > MAX_ENDPOINT_LENGTH) throw new Error(`${label} must be at most ${MAX_ENDPOINT_LENGTH} characters`);
+  if (/[\u0000-\u001f\u007f\s]/.test(raw)) throw new Error(`${label} must not contain whitespace or control characters`);
+  let url: URL;
+  try { url = new URL(raw); }
+  catch { throw new Error(`${label} must be an absolute URL`); }
+  if (url.protocol !== "https:") throw new Error(`${label} must use https`);
+  if (url.username !== "" || url.password !== "") throw new Error(`${label} must not embed credentials`);
+  if (url.search !== "") throw new Error(`${label} must not include a query string`);
+  if (url.hash !== "") throw new Error(`${label} must not include a fragment`);
+  if (url.pathname === "" || url.pathname === "/") throw new Error(`${label} must include a path such as ${JEV_SDK_PATH}`);
+  return { href: `${url.origin}${url.pathname}`, origin: url.origin, path: url.pathname };
+}
+
+/**
+ * Resolves the Jev endpoint. An invalid `SYSTEMONE_ENDPOINT` resolves to `unavailable` instead of silently falling
+ * back to the default: sending an operator's judgment payload to a provider they did not ask for would be a data leak.
+ */
+export function resolveJevEndpoint(env: NodeJS.ProcessEnv = process.env): JevEndpointResolution {
+  if (Object.hasOwn(env, SYSTEMONE_ENDPOINT_ENV)) {
+    try { return { status: "resolved", source: "environment", endpoint: parseEndpoint(env[SYSTEMONE_ENDPOINT_ENV] as string, SYSTEMONE_ENDPOINT_ENV) }; }
+    catch (error) { return { status: "unavailable", message: error instanceof Error ? error.message : `${SYSTEMONE_ENDPOINT_ENV} is invalid.` }; }
+  }
+  return { status: "resolved", source: "default", endpoint: parseEndpoint(JEV_DEFAULT_ENDPOINT, "the default Jev endpoint") };
+}
+
+/** Keyring account for an endpoint, so keys for different providers coexist instead of overwriting each other. */
+export function jevKeyringAccount(endpoint: ResolvedJevEndpoint): string {
+  return `systemone@sha256(${endpoint.href})`;
+}
+
 function store(): SecureKeyringStore {
   return createSecureKeyringStore(JEV_KEYRING_SERVICE);
 }
 
-function readStoredKey(secretStore: SecureKeyringStore = store()): string | undefined {
-  let payload: string | undefined;
-  try { payload = secretStore.read(JEV_KEYRING_ACCOUNT); }
-  catch (error) { throw new JevCredentialStoreError("read", error); }
-  if (payload === undefined) return undefined;
-  try {
-    const value: unknown = JSON.parse(payload);
-    if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid record");
-    const record = value as Partial<StoredJevKey>;
-    const keys = Object.keys(record);
+function requireEndpoint(endpoint: ResolvedJevEndpoint | undefined): ResolvedJevEndpoint {
+  if (endpoint) return endpoint;
+  const resolution = resolveJevEndpoint();
+  if (resolution.status === "unavailable") throw new Error(resolution.message);
+  return resolution.endpoint;
+}
+
+/**
+ * Version 1 records were written before the endpoint was configurable, so they are accepted only for the default
+ * endpoint.
+ */
+function parseStoredKey(payload: string, endpoint: ResolvedJevEndpoint): string {
+  let value: unknown;
+  try { value = JSON.parse(payload); }
+  catch { throw new Error("invalid record"); }
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid record");
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record);
+  if (record.version === 2) {
+    if (keys.length !== 3 || !["version", "endpoint", "apiKey"].every(key => Object.hasOwn(record, key))) throw new Error("invalid record fields");
+    if (record.endpoint !== endpoint.href) throw new Error("invalid or mismatched record");
+    return validateApiKey(record.apiKey);
+  }
+  if (record.version === 1) {
     if (keys.length !== 4 || !["version", "provider", "origin", "apiKey"].every(key => Object.hasOwn(record, key))) throw new Error("invalid record fields");
-    if (record.version !== 1 || record.provider !== "typesafe" || record.origin !== TYPESAFE_API_ORIGIN) throw new Error("invalid or mismatched record");
+    if (record.provider !== "typesafe" || record.origin !== TYPESAFE_API_ORIGIN) throw new Error("invalid or mismatched record");
+    if (endpoint.href !== JEV_DEFAULT_ENDPOINT) throw new Error("invalid or mismatched record");
     return validateApiKey(record.apiKey);
+  }
+  throw new Error("invalid record version");
+}
+
+function readStoredKey(secretStore: SecureKeyringStore, endpoint: ResolvedJevEndpoint): string | undefined {
+  try {
+    let payload = secretStore.read(jevKeyringAccount(endpoint));
+    if (payload === undefined && endpoint.href === JEV_DEFAULT_ENDPOINT) payload = secretStore.read(JEV_KEYRING_ACCOUNT);
+    return payload === undefined ? undefined : parseStoredKey(payload, endpoint);
   } catch (error) {
     throw new JevCredentialStoreError("read", error);
   }
 }
 
-export function resolveJevCredential(env: NodeJS.ProcessEnv = process.env, secretStore?: SecureKeyringStore): JevCredentialResolution {
-  if (Object.hasOwn(env, "TYPESAFE_API_KEY")) {
-    try { return { status: "present", source: "environment", apiKey: validateApiKey(env.TYPESAFE_API_KEY) }; }
-    catch { return { status: "unavailable", message: "TYPESAFE_API_KEY is present but invalid." }; }
+export function resolveJevCredential(
+  env: NodeJS.ProcessEnv = process.env,
+  endpoint?: ResolvedJevEndpoint,
+  secretStore: SecureKeyringStore = store(),
+): JevCredentialResolution {
+  let target: ResolvedJevEndpoint;
+  if (endpoint) target = endpoint;
+  else {
+    const resolution = resolveJevEndpoint(env);
+    if (resolution.status === "unavailable") return resolution;
+    target = resolution.endpoint;
   }
-  try {
-    const apiKey = readStoredKey(secretStore ?? store());
-    return apiKey === undefined ? { status: "missing" } : { status: "present", source: "keyring", apiKey };
-  } catch (error) {
+  if (Object.hasOwn(env, SYSTEMONE_API_KEY_ENV)) {
+    try { return { status: "present", source: "environment", apiKey: validateApiKey(env[SYSTEMONE_API_KEY_ENV]) }; }
+    catch { return { status: "unavailable", message: `${SYSTEMONE_API_KEY_ENV} is present but invalid.` }; }
+  }
+  const legacySet = Object.hasOwn(env, LEGACY_TYPESAFE_API_KEY_ENV);
+  if (legacySet && target.href === JEV_DEFAULT_ENDPOINT) {
+    try { return { status: "present", source: "environment", apiKey: validateApiKey(env[LEGACY_TYPESAFE_API_KEY_ENV]) }; }
+    catch { return { status: "unavailable", message: `${LEGACY_TYPESAFE_API_KEY_ENV} is present but invalid.` }; }
+  }
+  let stored: string | undefined;
+  try { stored = readStoredKey(secretStore, target); }
+  catch (error) {
     if (!(error instanceof JevCredentialStoreError)) throw error;
     return { status: "unavailable", message: error.message };
   }
+  if (stored !== undefined) return { status: "present", source: "keyring", apiKey: stored };
+  // A TypeSafe-issued credential is never sent to another endpoint, but it must not mask a credential stored for
+  // this endpoint either, so it is only reported once nothing for this endpoint resolves.
+  if (legacySet) {
+    return {
+      status: "unavailable",
+      message: `${LEGACY_TYPESAFE_API_KEY_ENV} is a TypeSafe credential and is not sent to ${target.href}; set ${SYSTEMONE_API_KEY_ENV} for that endpoint.`,
+    };
+  }
+  return { status: "missing" };
 }
 
-export function saveJevApiKey(apiKey: string, secretStore: SecureKeyringStore = store()): void {
-  const record: StoredJevKey = { version: 1, provider: "typesafe", origin: TYPESAFE_API_ORIGIN, apiKey: validateApiKey(apiKey) };
-  try { secretStore.write(JEV_KEYRING_ACCOUNT, JSON.stringify(record)); }
+export function saveJevApiKey(apiKey: string, endpoint?: ResolvedJevEndpoint, secretStore: SecureKeyringStore = store()): void {
+  const target = requireEndpoint(endpoint);
+  const record: StoredJevKey = { version: 2, endpoint: target.href, apiKey: validateApiKey(apiKey) };
+  try { secretStore.write(jevKeyringAccount(target), JSON.stringify(record)); }
   catch (error) { throw new JevCredentialStoreError("write", error); }
 }
 
-export function removeJevApiKey(secretStore: SecureKeyringStore = store()): void {
-  try { secretStore.remove(JEV_KEYRING_ACCOUNT); }
-  catch (error) { throw new JevCredentialStoreError("remove", error); }
+export function removeJevApiKey(endpoint?: ResolvedJevEndpoint, secretStore: SecureKeyringStore = store()): void {
+  const target = requireEndpoint(endpoint);
+  try {
+    secretStore.remove(jevKeyringAccount(target));
+    if (target.href === JEV_DEFAULT_ENDPOINT) secretStore.remove(JEV_KEYRING_ACCOUNT);
+  } catch (error) { throw new JevCredentialStoreError("remove", error); }
 }

package/node_modules/pi-mcp-adapter/mcp-auth-flow.ts

@@ -1191,9 +1191,8 @@ export async function getValidToken(
     }
   }
 
-  // No expiration info or no refresh token, assume valid
   authority()
-  return entry.tokens
+  return null
 }
 
 /**

package/node_modules/pi-mcp-adapter/mcp-code.ts

@@ -213,7 +213,7 @@ export async function runMcpScript(
   let evaluationAttempts = 0;
   let evaluationBytes = 0;
   let evaluationTokensRemaining = jevSettings.maxEvaluationTokensPerScript;
-  const tokenBudgetExhausted = (): JevEvaluationEnvelope => ({ ok: false, error: { code: "budget_exhausted", message: "TypeSafe evaluation token budget exhausted." } });
+  const tokenBudgetExhausted = (): JevEvaluationEnvelope => ({ ok: false, error: { code: "budget_exhausted", message: "Jev evaluation token budget exhausted." } });
   const chargeEvaluationTokens = (envelope: JevEvaluationEnvelope): JevEvaluationEnvelope => {
     if (!envelope.ok) return envelope;
     const used = envelope.data.usage.inputTokens + envelope.data.usage.outputTokens;
@@ -226,16 +226,16 @@ export async function runMcpScript(
   };
   const admitEvaluation = (input: unknown): JevEvaluationEnvelope | undefined => {
     if (++evaluationAttempts > jevSettings.maxEvaluationsPerScript) {
-      return { ok: false, error: { code: "budget_exhausted", message: "TypeSafe evaluation count budget exhausted." } };
+      return { ok: false, error: { code: "budget_exhausted", message: "Jev evaluation count budget exhausted." } };
     }
     if (evaluationTokensRemaining === 0) return tokenBudgetExhausted();
     let serialized: string | undefined;
     try { serialized = JSON.stringify(input); }
-    catch { return { ok: false, error: { code: "invalid_request", message: "Invalid TypeSafe evaluation request." } }; }
-    if (serialized === undefined) return { ok: false, error: { code: "invalid_request", message: "Invalid TypeSafe evaluation request." } };
+    catch { return { ok: false, error: { code: "invalid_request", message: "Invalid Jev evaluation request." } }; }
+    if (serialized === undefined) return { ok: false, error: { code: "invalid_request", message: "Invalid Jev evaluation request." } };
     const bytes = Buffer.byteLength(serialized, "utf8");
     if (bytes > jevSettings.maxEvaluationBytesPerScript - evaluationBytes) {
-      return { ok: false, error: { code: "budget_exhausted", message: "TypeSafe evaluation byte budget exhausted." } };
+      return { ok: false, error: { code: "budget_exhausted", message: "Jev evaluation byte budget exhausted." } };
     }
     evaluationBytes += bytes;
     return undefined;
@@ -257,7 +257,7 @@ export async function runMcpScript(
     envelope = chargeEvaluationTokens(envelope);
     throwIfAborted(callSignal);
     if (!reserveIntermediateBytes(JSON.stringify(envelope))) {
-      envelope = { ok: false, error: { code: "budget_exhausted", message: "TypeSafe evaluation exceeds the remaining mcpScript intermediate transfer budget (16 MiB per script)." } };
+      envelope = { ok: false, error: { code: "budget_exhausted", message: "Jev evaluation exceeds the remaining mcpScript intermediate transfer budget (16 MiB per script)." } };
     }
     calls[index] = envelope.ok
       ? {

package/node_modules/pi-mcp-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mcp-adapter",
-  "version": "2.36.0",
+  "version": "2.37.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
   "type": "module",
   "types": "./index.ts",
@@ -185,7 +185,7 @@
     "zod": "^3.25.0 || ^4.0.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.84.1 || ^0.85.0 || ^0.86.0",
+    "@earendil-works/pi-ai": "^0.84.1 || ^0.85.0 || ^0.86.0 || ^0.87.0",
     "@earendil-works/pi-tui": "*",
     "typebox": "*",
     "zod": "^3.25.0 || ^4.0.0"
@@ -202,9 +202,9 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.86.0",
-    "@earendil-works/pi-coding-agent": "0.86.0",
-    "@earendil-works/pi-tui": "0.86.0",
+    "@earendil-works/pi-ai": "0.87.0",
+    "@earendil-works/pi-coding-agent": "0.87.0",
+    "@earendil-works/pi-tui": "0.87.0",
     "@modelcontextprotocol/conformance": "0.1.16",
     "@types/bun": "^1.0.0",
     "@types/cross-spawn": "6.0.6",

package/node_modules/pi-mcp-adapter/semantic-search.ts

@@ -114,10 +114,10 @@ export async function semanticSearch(
   try {
     settings = resolveSemanticJevSettings(state);
   } catch {
-    return { ok: false, error: { code: "invalid_request", message: "Invalid TypeSafe semantic search settings." } };
+    return { ok: false, error: { code: "invalid_request", message: "Invalid Jev semantic search settings." } };
   }
   if (!settings.semanticSearch) {
-    return { ok: false, error: { code: "disabled", message: "TypeSafe semantic search is disabled." } };
+    return { ok: false, error: { code: "disabled", message: "Jev semantic search is disabled." } };
   }
   if (settings.allowedServers.length === 0) {
     return { ok: false, error: { code: "data_policy_denied", message: "Semantic search is enabled, but settings.jev.allowedServers is empty. Run /mcp jev setup or allow specific MCP servers." } };
@@ -166,7 +166,7 @@ export async function semanticSearch(
   }
   const answer = envelope.data.answers.match;
   if (!answer || answer.type !== "choice") {
-    return { ok: false, error: { code: "invalid_response", message: "TypeSafe returned an invalid semantic search response." } };
+    return { ok: false, error: { code: "invalid_response", message: "Jev returned an invalid semantic search response." } };
   }
   const ranked = candidates
     .map(candidate => ({ candidate, probability: answer.probabilities[candidate.id] ?? 0 }))

package/node_modules/pi-mcp-adapter/types.ts

@@ -589,6 +589,8 @@ export type { JevAnswer, JevErrorCode, JevEvaluateInput, JevEvaluationData, JevE
 
 export interface McpSettings {
   toolPrefix?: ToolPrefix;
+  /** Allow agents to persist remote MCP endpoints with the install action. Defaults to true. */
+  allowInstall?: boolean;
   /** Show the plug prefix in MCP status and connection text (default: true). Set to false to disable it. */
   showStatusIcon?: boolean;
   /** Footer status verbosity: full details, compact connected/enabled count, or no footer status. Defaults to full. */
@@ -603,6 +605,8 @@ export interface McpSettings {
   agentPluginPaths?: string[];
   idleTimeout?: number; // minutes, default 10, 0 to disable
   requestTimeoutMs?: number; // milliseconds, overrides the SDK request timeout when > 0
+  /** Defer lazy runtime startup even when persisted metadata is missing or invalid. Defaults to false. */
+  deferWithMissingMetadata?: boolean;
   directTools?: boolean | "search";
   /** Register per-server mcp__<server> namespace proxies. Defaults to true. */
   namespaceProxyTools?: boolean;
@@ -620,7 +624,9 @@ export interface McpSettings {
   warnOnLargeDirectTools?: boolean;
   /** Register the trusted MCP-only JavaScript scripting tool. Defaults to true; set false to hide it. */
   scriptMode?: boolean;
-  /** Optional TypeSafe Jev integrations. A valid key enables semantic search; script evaluation remains disabled by default. */
+  /** Expose MCP resources as tools (default: true). Set to false to disable globally across all servers. */
+  exposeResources?: boolean;
+  /** Optional Jev (System One) integrations. A valid key enables semantic search; script evaluation remains disabled by default. */
   jev?: false | {
     semanticSearch?: boolean;
     scriptEvaluation?: boolean;

package/node_modules/pi-multi-account/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.23.2] — 2026-09-24
+
+### Fixed
+
+- Sessions hosted by pi-web's session daemon no longer deactivate after the first one. The in-process root-activation lease (designed for terminal Pi's `/reload` and in-process children) misclassified every later pi-web session as a subagent child, leaving it in `subagent-child-passive` mode with failover, preflight and auto-continue silently disabled. When `PI_WEB_SESSION=1` is present, each session now activates as an independent root; any other multi-session SDK host can opt in with the host-neutral `PI_MULTI_ACCOUNT_INDEPENDENT_ROOTS=1`. Genuine pi-subagents children still run in a runner process marked `PI_SUBAGENT_CHILD=1` and remain passive.
+- In-process independent roots and same-session rehydrates now share a process-scoped canonical child proxy and publication lifetime. A sibling can exit in either order without restoring real OAuth into child-facing `auth.json` or orphaning `models.json` loopback routes; only the final root closes the listener and restores auth. A root whose proxy is disabled still retires public numbered aliases before another root publishes placeholders, and keeps that listener alive through handoff. The surviving root handles newly discovered slots, while explicit `PI_SUBAGENT_CHILD` remains passive.
+
+## [1.23.1] — 2026-09-23
+
+### Fixed
+
+- Restore `pi-ai` as an installed runtime dependency for the OAuth/catalog bridge (#75). Pi-managed npm, bun and pnpm extension installs deliberately omit peer dependencies; v1.23.0 made pi-ai peer-only, so a fresh install could not log into a numbered subscription account. Native provider transports remain bound to the running Pi host, not this bridge copy. The package check now rejects future peer-only regressions.
 
 ## [1.23.0] — 2026-09-23
 

package/node_modules/pi-multi-account/README.md

@@ -27,11 +27,12 @@ pi install npm:pi-multi-account
 Restart Pi or run `/reload` after installation.
 
 Requires Node 22+ and Agent Pi / pi-ai **>=0.85.1, <0.88.0** (CI covers 0.85.1, 0.86.1 and 0.87.1).
-Pi core packages are peers, not a private pinned transport dependency. Provider wrappers use Pi's
-host-bound imports, so the request adapter and host context format stay together; a stale nested
-pi-ai cannot silently remove tools or system instructions. Standalone SDK callers must pair their
-context with the installed pi-ai version. The OAuth/catalog bridge remains a separate, best-effort
-compatibility layer: unavailable subscription login does not prevent API-key account discovery.
+Pi's host package is a peer. `pi-ai` is a runtime dependency for the OAuth/catalog bridge:
+Pi-managed installs intentionally do not install extension peer dependencies, but subscription
+login must be able to locate pi-ai on disk. Provider transports still use Pi's **host-bound**
+imports, not that filesystem-resolved bridge copy, so a stale nested pi-ai cannot remove tools or
+system instructions. Standalone SDK callers must pair their context with the installed pi-ai
+version. If the OAuth bridge is unavailable, API-key account discovery still works.
 
 Kimi OAuth spares remain available in `/login`, but are not written to `models.json`: without a
 Kimi child OAuth proxy those aliases would be resolvable but unauthenticated. Only real API-key
@@ -178,7 +179,21 @@ Background attempts share the same cooldown and invalidation state as foreground
 
 ### pi-subagents and delegation-broker compatibility
 
-`pi-subagents` marks native child processes with `PI_SUBAGENT_CHILD=1` and owns their explicit model plus `fallbackModels` chain. Concurrent in-process SDK sessions also stay passive while a root session activation is live. The root lease is released at session shutdown, so `/reload`, `/new` and replacement root sessions do not permanently lose routing ownership. This is process-local ownership, not detection based on model names or a permanent first-factory flag. In those children this extension stays loaded only for provider/account registration, OAuth request shaping, and catalog support. It deliberately does **not** restore the interactive process's remembered model, persist the child's model as a user preference, switch models, queue work, or auto-continue after errors. The original provider error is returned unchanged so the parent runner can advance its verified fallback chain without a second router competing for model identity.
+`pi-subagents` marks native child processes with `PI_SUBAGENT_CHILD=1` and owns their explicit model plus `fallbackModels` chain. Under terminal Pi, a distinct concurrent in-process child also stays passive while a root activation is live. A replacement with the **same nonempty session ID** reacquires that root's failover ownership without closing its child proxy. The root lease is released at final session shutdown, so `/reload` and `/new` do not permanently lose routing ownership. In passive children this extension stays loaded only for provider/account registration, OAuth request shaping, and catalog support. It deliberately does **not** restore the interactive process's remembered model, persist the child's model as a user preference, switch models, queue work, or auto-continue after errors. The original provider error is returned unchanged so the parent runner can advance its verified fallback chain without a second router competing for model identity.
+
+### Multi-session hosts (pi-web and other in-process SDK hosts)
+
+Some hosts run many independent sessions in a single long-lived process — pi-web's session daemon, or in-process SDK hosts such as Enso (one session per chat thread). Terminal Pi's in-process root-activation lease would incorrectly demote every session but the first to passive in those hosts.
+
+- Under pi-web (`PI_WEB_SESSION=1`, set by the daemon itself) every session activates as an independent root automatically.
+- Any other multi-session host opts in by exporting `PI_MULTI_ACCOUNT_INDEPENDENT_ROOTS=1` in the host process. Set this only when each session truly owns its model; sessions that share one model identity must keep the default single-root behavior.
+- Genuine `pi-subagents` children are unaffected either way: they run in a runner process marked `PI_SUBAGENT_CHILD=1`, which always takes precedence and stays passive.
+
+Hosts should not set `PI_WEB_SESSION` themselves — other extensions read it to detect pi-web specifically.
+
+In one process, independent roots share one canonical loopback proxy and its child-facing auth/models publication while any root has the child proxy enabled. Closing one root cannot expose its sibling's real OAuth or remove the route its bare children use; the final live root closes the listener and restores the original auth. A rehydrated session with the same ID replaces the old instance's failover ownership rather than counting as a second root. Another process holding the canonical port remains the publisher; a foreign listener is never allowed to overwrite its shared files.
+
+Roots with `childProxy: false` still participate in the shared lifetime if another root publishes placeholders. Any public numbered alias they registered earlier is moved to loopback **before** the placeholder appears; they keep the canonical listener alive if the publisher exits first, and only the final root restores auth. With no other publishing root, disabling `childProxy` retains the usual direct route. Hosts should still keep one consistent setting across concurrent roots.
 
 [`pi-delegation-broker`](https://github.com/Sarrius/pi-delegation-broker) is an optional companion for splitting work among isolated child agents, with task budgets, reports and verification. Each extension works independently and depends on Agent Pi, not on the other extension. Together, Multi Account manages your interactive account rotation while the broker delegates through Pi's registered providers and models. Neither installs or initializes the other.