{"record":{"id":"ec973ed154f649d0","repo":"coleam00/Archon","slug":"run-config-key-assistants-pi-env-cannot-apply-p","errorCode":null,"errorMessage":"Run config key 'assistants.pi.env' cannot apply: Pi extension environment mutates process.env and is process-scoped.","messagePattern":"Run config key 'assistants\\.pi\\.env' cannot apply: Pi extension environment mutates process\\.env and is process-scoped\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/config/run-config.ts","lineNumber":126,"sourceCode":"      throw new Error(\n        `Invalid run config at '${issuePath}': unknown provider '${error.issue.provider}'.` +\n          (available ? ` Available: ${available}.` : ' No providers are registered.')\n      );\n    }\n    throw new Error(`Invalid run config at '${issuePath}': ${error.message}.`);\n  }\n}\n\n/** Validate and normalize constraints owned by the live provider registry and lifecycle. */\nexport function normalizeRunConfigSemantics(layer: WorkflowRunConfigLayer): WorkflowRunConfigLayer {\n  if (layer.assistant !== undefined) {\n    assertRegisteredProvider(layer.assistant, 'assistant');\n  }\n  const assistants: Record<string, Record<string, unknown>> = {};\n  for (const [provider, defaults] of Object.entries(layer.assistants ?? {})) {\n    assertRegisteredProvider(provider, `assistants.${provider}`);\n    if (provider === 'pi' && Object.hasOwn(defaults, 'env')) {\n      throw new Error(\n        \"Run config key 'assistants.pi.env' cannot apply: Pi extension environment mutates \" +\n          'process.env and is process-scoped.'\n      );\n    }\n    if (provider === 'pi' && Object.hasOwn(defaults, 'maxConcurrent')) {\n      throw new Error(\n        \"Run config key 'assistants.pi.maxConcurrent' cannot apply: Pi concurrency is \" +\n          'initialized once for the process lifetime.'\n      );\n    }\n    try {\n      assistants[provider] = getRegistration(provider).parseRunConfig(defaults);\n    } catch (error) {\n      if (error instanceof InvalidProviderRunConfigError) {\n        const suffix = error.fieldPath ? `.${error.fieldPath}` : '';\n        throw new Error(\n          `Invalid run config at 'assistants.${provider}${suffix}': ${error.message}.`\n        );","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/core/src/config/run-config.ts#L108-L144","documentation":"Archon run configs allow per-provider assistant defaults, but the 'pi' provider rejects an 'env' key. Pi extension environment variables mutate process.env, which is process-scoped and cannot be applied per-run, so the config layer refuses the key at normalization time instead of silently ignoring it.","triggerScenarios":"Calling runConfig(), parseWorkflowRunConfig(), or unsealWorkflowRunConfig() with a config layer containing assistants: { pi: { env: {...} } }.","commonSituations":"Copying a general assistant env block into the pi assistant section of a run config or workflow frontmatter; assuming all providers support per-run env overrides.","solutions":["Remove the 'env' key from assistants.pi in the run config","Set Pi extension environment variables in the process environment (shell, .env, or process.env) instead of the run config","Move env setup to the deployment/startup layer that launches the Archon process"],"exampleFix":"// before\nassistants:\n  pi:\n    env:\n      PI_TOKEN: abc\n// after\nassistants:\n  pi: {}  # set PI_TOKEN in the process environment instead","handlingStrategy":"validation","validationCode":"function assertPiAssistantDefaults(defaults) { if (defaults && ('env' in defaults)) throw new Error(\"assistants.pi.env is not supported; set env in the process environment\"); }","typeGuard":"function hasPiEnv(layer) { return typeof layer?.assistants?.pi === 'object' && layer.assistants.pi !== null && 'env' in layer.assistants.pi; }","tryCatchPattern":"try { cfg = parseWorkflowRunConfig(doc, source); } catch (e) { if (String(e.message).includes(\"assistants.pi.env\")) { console.error('Move pi env vars to the process environment'); } throw e; }","preventionTips":["Never put 'env' under assistants.pi; keep pi env in shell/.env/process startup","Lint run config files for the assistants.pi.env key in CI","Share a typed schema of valid pi assistant keys with the team"],"tags":["config","pi-provider","env"],"backgroundTag":"unsupported-config-key","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}