@capagents/forgeqe 1.3.1 → 2.0.0

package/src/code/find.ts

@@ -13,11 +13,32 @@ import { CAUSE_TEXT, flakyReport, quarantined, recordResults, RELEASE_AFTER, set
 import { loadSkills } from "../skills/registry.ts"
 import { prompt } from "../prompts.ts"
 import { domainNotes } from "../domain.ts"
+import { guardrailsNotes } from "../guardrails.ts"
 
 const LIST_ROUNDS = 3
 const LIST_TIMEOUT_SECONDS = 180
 const OUTPUT_CHARS = 6_000
 
+/**
+ * ForgeQE runs Scribe's list command without asking, so it takes only a test framework's own listing: Scribe reads the
+ * repository, and a file in it could talk Scribe into any command. The run command is shown to the user first instead.
+ */
+const LIST_RUNNER =
+  /^(?:(?:(?:npx(?:\s+--no-install)?|pnpm(?:\s+exec)?|yarn|bunx|bun\s+x)\s+)?(?:playwright\s+test|jest|vitest|mocha)|(?:(?:python3?|py)\s+-m\s+|(?:uv|poetry)\s+run\s+)?pytest|dotnet\s+test)(?=\s|$)/i
+const LIST_FLAG = /(?:^|\s)(?:--list|--listTests|--list-tests|--collect-only|--co|--dry-run)(?=[\s=]|$)/
+/** Characters that chain, substitute, or redirect in sh or cmd.exe. */
+const SHELL_SYNTAX = /[;&|`$<>()\r\n%]/
+
+/** Whether ForgeQE may run `command` unasked as a list command: one test runner, a listing flag, no shell syntax. */
+export function listCommandAllowed(command: string): boolean {
+  const c = command.trim()
+  if (!c || SHELL_SYNTAX.test(c)) return false
+  const runner = LIST_RUNNER.exec(c)
+  if (!runner) return false
+  const rest = c.slice(runner[0].length)
+  return LIST_FLAG.test(rest) || (/vitest$/i.test(runner[0]) && /^\s+list(?=\s|$)/.test(rest))
+}
+
 export const findAgentPrompt = () => prompt("find-tests")
 
 export const FIND_AGENT: AgentSpec = {
@@ -176,6 +197,7 @@ export async function findTests(opts: {
     repo,
     profile: opts.config.llm,
     domain: domainNotes(opts.config),
+    guardrails: guardrailsNotes(opts.config),
     model: opts.config.code.model,
     bin: opts.config.code.opencode,
     readDirs: [repo],
@@ -195,6 +217,10 @@ export async function findTests(opts: {
     let report = reply.report
     let listed = false
     for (let round = 1; round <= LIST_ROUNDS && clean(report.tests).length && report.list_command?.trim() && !opts.signal?.aborted; round++) {
+      if (!listCommandAllowed(report.list_command!)) {
+        emit({ type: "code", kind: "info", text: `ForgeQE does not run this list command, which is not a test framework's own listing: ${report.list_command}` })
+        break
+      }
       emit({ type: "code", kind: "info", text: `ForgeQE lists the selected tests: ${report.list_command}` })
       const run = await runTest({ command: report.list_command!, cwd: repo, timeoutSeconds: LIST_TIMEOUT_SECONDS, signal: opts.signal, hide: privateEnvNames(opts.config) })
       if (opts.signal?.aborted) break

package/src/code/loop.ts

@@ -15,6 +15,7 @@ import { CODE_GRAPH_SERVER, codeGraphTools } from "./graph/tools.ts"
 import { localToolServer } from "../mcp/server.ts"
 import type { ToolContext } from "../mcp/tools.ts"
 import { addWrittenTest, notesSection, readNotes, saveNotes } from "./notes.ts"
+import { environmentBrief } from "../environments.ts"
 import { canReplay, replayRun, savedReplay, type Replay } from "./replay.ts"
 import { openSession, READ_AGENT, TEST_AGENT, type OpencodeSession, type PromptOutcome } from "./runtime.ts"
 import { failureContext } from "./slices.ts"
@@ -48,6 +49,7 @@ import { runTestCommand } from "./testrun.ts"
 import { changedFiles, jobChanges, ownPaths, preexisting, protectPatterns, restoreRemoved, restoreSnapshot, snapshot, snapshotFiles } from "./worktree.ts"
 import { loadSkills } from "../skills/registry.ts"
 import { domainNotes } from "../domain.ts"
+import { guardrailsNotes } from "../guardrails.ts"
 
 function realpathOr(dir: string): string {
   try {
@@ -281,6 +283,7 @@ export async function runCodeAgent(opts: {
       repo,
       profile: config.llm,
       domain: domainNotes(config),
+      guardrails: guardrailsNotes(config),
       model: config.code.model,
       bin: config.code.opencode,
       readDirs,
@@ -379,7 +382,7 @@ export async function runCodeAgent(opts: {
     let prompt =
       resumed && earlier?.stage === "writing"
         ? carryOnPrompt(liveOn)
-        : `${resumed ? `${RESUMED_NOTE}\n\n` : ""}${firstPrompt(handoff, { ...(live ? { liveBrowserDir: live.dir, liveOn } : {}), ...(known ? { notes: notesSection(known) } : {}), ...(profileText ? { profile: profileText } : {}), ...(opts.existingTest ? { existing: opts.existingTest } : {}), ...(opts.target ? { target: opts.target } : {}) })}`
+        : `${resumed ? `${RESUMED_NOTE}\n\n` : ""}${firstPrompt(handoff, { ...(live ? { liveBrowserDir: live.dir, liveOn } : {}), ...(known ? { notes: notesSection(known) } : {}), ...(profileText ? { profile: profileText } : {}), ...(opts.existingTest ? { existing: opts.existingTest } : {}), ...(opts.target ? { target: opts.target } : {}), ...(environmentBrief(config, "code") ? { environment: environmentBrief(config, "code") } : {}) })}`
     if (prepared) {
       stage = "writing"
       saveSession()

package/src/code/prompt.ts

@@ -154,7 +154,7 @@ function existingSection(e: ExistingTest): string[] {
   ]
 }
 
-export function firstPrompt(handoff: Handoff, opts: { liveBrowserDir?: string; liveOn?: boolean; notes?: string; profile?: string; existing?: ExistingTest; target?: TestTarget } = {}): string {
+export function firstPrompt(handoff: Handoff, opts: { liveBrowserDir?: string; liveOn?: boolean; notes?: string; profile?: string; existing?: ExistingTest; target?: TestTarget; environment?: string } = {}): string {
   const live = opts.liveBrowserDir
     ? opts.liveOn
       ? `Your live_browser_* tools are on because the replay failed at a step; use them on that step's page. They save snapshots and screenshots in ${opts.liveBrowserDir}.`
@@ -176,6 +176,7 @@ export function firstPrompt(handoff: Handoff, opts: { liveBrowserDir?: string; l
     ...(opts.existing ? existingSection(opts.existing) : opts.target ? targetSection(opts.target) : []),
     ...(opts.profile ? [opts.profile, ""] : []),
     ...(opts.notes ? [opts.notes, ""] : []),
+    ...(opts.environment ? [opts.environment, ""] : []),
     handoff.markdown,
     "",
     `(The same handoff is saved at ${handoff.file}; you do not need to read it again.)`,

package/src/code/prreview.ts

@@ -15,6 +15,7 @@ import type { Price } from "../usage.ts"
 import { openSession, type AgentSpec, type OpencodeSession } from "./runtime.ts"
 import { prompt } from "../prompts.ts"
 import { domainNotes } from "../domain.ts"
+import { guardrailsNotes } from "../guardrails.ts"
 
 const API = "api-version=7.1"
 /** The diff is shown in the prompt up to this size; the reviewer runs git diff for the rest. */
@@ -469,6 +470,7 @@ export async function reviewPullRequest(opts: {
       repo: co.tree,
       profile,
       domain: domainNotes(opts.config),
+      guardrails: guardrailsNotes(opts.config),
       model: profile === opts.config.llm ? opts.config.code.model : undefined,
       bin: opts.config.code.opencode,
       readDirs: [co.tree],

package/src/code/review.ts

@@ -3,6 +3,7 @@ import path from "node:path"
 
 import type { CodeEvent, CodeReview, Usage } from "../types.ts"
 import { privateEnvNames } from "../childEnv.ts"
+import { environmentBrief } from "../environments.ts"
 import type { AppConfig } from "../config.ts"
 import type { Handoff } from "./handoff.ts"
 import { openSession, type AgentSpec, type OpencodeSession } from "./runtime.ts"
@@ -12,6 +13,7 @@ import type { Price } from "../usage.ts"
 import { prompt } from "../prompts.ts"
 import { domainNotes } from "../domain.ts"
 import type { TestTarget } from "./prompt.ts"
+import { guardrailsNotes } from "../guardrails.ts"
 
 const OUTPUT_CHARS = 4_000
 /** Changed files are shown in the prompt up to these sizes; the reviewer reads the rest itself. */
@@ -118,7 +120,7 @@ export function changedFiles(repo: string, paths: string[]): string[] {
   return lines
 }
 
-export function reviewPrompt(input: ReviewInput, repo?: string): string {
+export function reviewPrompt(input: ReviewInput, repo?: string, environment?: string): string {
   const { handoff, report } = input
   const out = input.output.length > OUTPUT_CHARS ? `…${input.output.slice(-OUTPUT_CHARS)}` : input.output
   const changed = input.changes || report.changed || []
@@ -127,6 +129,7 @@ export function reviewPrompt(input: ReviewInput, repo?: string): string {
     `Review the test the coding agent wrote for this goal: ${handoff.goal}`,
     `The handoff it worked from: ${handoff.file}`,
     ...(checks ? ["", "The browser agent's checks, from the handoff:", checks] : []),
+    ...(environment ? ["", environment, "An environment's URL, host or path written into the test, where these settings or the repository's own should be read, is a correctness issue."] : []),
     "",
     ...(input.target
       ? [
@@ -207,6 +210,7 @@ export function openReviewer(opts: {
           repo: opts.repo,
           profile: reviewProfile,
           domain: domainNotes(opts.config),
+          guardrails: guardrailsNotes(opts.config),
           model: reviewProfile === opts.config.llm ? opts.config.code.model : undefined,
           bin: opts.config.code.opencode,
           readDirs: opts.readDirs,
@@ -224,7 +228,7 @@ export function openReviewer(opts: {
           ...(opts.mcp ? { mcp: opts.mcp } : {}),
         })
       }
-      let reply = await session.prompt(reviewPrompt(input, opts.repo))
+      let reply = await session.prompt(reviewPrompt(input, opts.repo, environmentBrief(opts.config, "code") || undefined))
       if (!reply.report && !reply.error) reply = await session.prompt("Give the structured result: approved, summary, and issues.")
       Object.assign(usage, session.usage)
       const r = reply.report

package/src/code/runtime.ts

@@ -5,6 +5,7 @@ import path from "node:path"
 
 import { createOpencodeClient, type OpencodeClient } from "@opencode-ai/sdk/v2"
 
+import { COPILOT_PROVIDER_ID, copilotProfileError, RUNTIME_AUTH_ENV, runtimeAuthContent } from "../copilot.ts"
 import { entraGateway } from "../entra.ts"
 import { missingKey, type LlmProfile } from "../llm.ts"
 import type { CodeEvent, FileAction, PlanItem, Usage } from "../types.ts"
@@ -122,11 +123,27 @@ export function providerFor(profile: LlmProfile): { provider: Record<string, unk
         },
         model: { providerID: "forgeqe", modelID: profile.model },
       }
+    case "github_copilot": {
+      const bad = copilotProfileError(profile)
+      if (bad) throw new Error(bad)
+      // The agent runtime's own GitHub Copilot provider; its sign-in comes in RUNTIME_AUTH_ENV (copilotSecrets).
+      return { provider: {}, model: { providerID: COPILOT_PROVIDER_ID, modelID: profile.model } }
+    }
     default:
       throw new Error(`The coding agent needs a live LLM profile; "${profile.provider}" has no model. Pick one with --profile or set code.model.`)
   }
 }
 
+/**
+ * For a Copilot model, the saved Copilot sign-in as the agent runtime reads it from its environment, so it never sits
+ * in the runtime's auth.json where the agent's shell could read it. Without a saved one the runtime uses its own sign-in.
+ */
+export function copilotSecrets(model: ModelRef, saved?: string): Record<string, string> {
+  if (model.providerID !== COPILOT_PROVIDER_ID) return {}
+  const content = runtimeAuthContent(saved)
+  return content ? { [RUNTIME_AUTH_ENV]: content } : {}
+}
+
 function parseModel(ref: string): ModelRef {
   const i = ref.indexOf("/")
   if (i <= 0) throw new Error(`code.model must be provider/model, got "${ref}".`)
@@ -266,6 +283,9 @@ export const BASH_PERMISSION = {
   "*git -c * push*": "deny",
   "gh repo delete*": "deny",
   "*gh repo delete*": "deny",
+  // Containers start through ForgeQE's services and mock_service tools, which run only what forgeqe.yaml declares: a
+  // container command from the agent could mount the whole disk or run privileged (docs/CONTAINERS.md).
+  ...Object.fromEntries(["docker", "podman", "nerdctl", "docker-compose", "podman-compose"].flatMap((c) => [[`${c} *`, "deny"], [`${c}`, "deny"], [`* ${c} *`, "deny"], [`*/${c} *`, "deny"], [`*${c}.exe*`, "deny"]])),
 }
 
 /**
@@ -524,6 +544,11 @@ export function withDomain(agent: AgentSpec, domain: string | null): AgentSpec {
   return domain && !prompt.includes(domain) ? { ...agent, prompt: `${prompt}\n\n${domain}` } : agent
 }
 
+/** The agent with the team's guardrails added to its instructions (once), last, so nothing after them overrides them. */
+export function withGuardrails(agent: AgentSpec, guardrails: string | null): AgentSpec {
+  return guardrails && !agent.prompt.includes(guardrails) ? { ...agent, prompt: `${agent.prompt}\n\n${guardrails}` } : agent
+}
+
 export async function openSession<R = AgentReport>(opts: {
   repo: string
   profile: LlmProfile
@@ -561,12 +586,17 @@ export async function openSession<R = AgentReport>(opts: {
    * not apply (a judge that is given the domain as data).
    */
   domain: string | null
+  /**
+   * The team's guardrails (guardrailsNotes: the rules in .forgeqe/guardrails), added to every agent's instructions.
+   * Required for the same reason as domain; null when the team has set none, or for a judge scoring other agents.
+   */
+  guardrails: string | null
   /** Values for {env:} references in `mcp` that are not in this terminal (e.g. base64 of email:token). */
   secrets?: Record<string, string>
   /** Who this session is in the usage meter. Default Scribe. */
   role?: Role
 }): Promise<OpencodeSession<R>> {
-  const missing = opts.model ? null : missingKey(opts.profile)
+  const missing = opts.model ? null : missingKey(opts.profile, "agent")
   if (missing) throw new Error(missing)
   const bin = findOpencode(opts.bin)
   if (!bin) throw new Error(`The agent runtime was not found. ${INSTALL_HINT}`)
@@ -594,8 +624,8 @@ export async function openSession<R = AgentReport>(opts: {
       profile: gateway?.profile || opts.profile,
       model: opts.model,
       readDirs,
-      agent: withDomain(agent, opts.domain),
-      agents: opts.agents?.map((a) => withDomain(a, opts.domain)),
+      agent: withGuardrails(withDomain(agent, opts.domain), opts.guardrails),
+      agents: opts.agents?.map((a) => withGuardrails(withDomain(a, opts.domain), opts.guardrails)),
       mcp: opts.mcp,
       protect,
       readOnly: skillPaths,
@@ -607,6 +637,7 @@ export async function openSession<R = AgentReport>(opts: {
     throw err
   }
   const { config, model } = built
+  Object.assign(secrets, copilotSecrets(model))
   const pluginDir = mkdtempSync(path.join(os.tmpdir(), "forgeqe-runtime-"))
   const shellHidden = [...(opts.hide || []), ...Object.keys(secrets), ...envRefs(config), "OPENCODE_CONFIG_CONTENT"]
   config.plugin = [...((config.plugin as string[] | undefined) || []), hideEnvPlugin(pluginDir, shellHidden)]

package/src/commands.ts

@@ -7,6 +7,8 @@ export type ShellCommand =
   /** value unset: toggle. */
   | { type: "details"; value?: boolean }
   | { type: "profile"; name: string }
+  /** name unset: list the test environments; else switch to that one (env.yaml). */
+  | { type: "env"; name?: string }
   | { type: "logs"; shots: boolean }
   | { type: "skills"; name?: string }
   | { type: "features" }
@@ -36,6 +38,7 @@ export const HELP = [
   "  /headed on|off     show the browser (live profiles)",
   "  /details [on|off]  show everything the agents do (reasoning, every file read, engine logs); off: just progress",
   "  /profile <name>    switch LLM profile (or press tab)",
+  "  /env [name]        the test environments in env.yaml and their apps, or switch to one",
   "  /logs [shots]      save this session's log and runs in one archive to share (shots: with screenshots)",
   "  /features          what ForgeQE can do, and what each capability still needs here",
   "  /init              set ForgeQE up in this folder: forgeqe.yaml, llms.json, editable prompts, skills, knowledge",
@@ -49,7 +52,7 @@ export const HELP = [
   "Select text with the mouse to copy it.",
 ].join("\n")
 
-const COMMANDS = new Set(["help", "?", "exit", "quit", "q", "clear", "stop", "headed", "details", "verbose", "profile", "p", "logs", "skills", "features", "auth", "signin", "init", "rerun"])
+const COMMANDS = new Set(["env", "help", "?", "exit", "quit", "q", "clear", "stop", "headed", "details", "verbose", "profile", "p", "logs", "skills", "features", "auth", "signin", "init", "rerun"])
 
 /** Session controls; every other line, including one that starts with a path, goes to the agent as text. */
 export function parseCommand(raw: string): ShellCommand {
@@ -81,6 +84,8 @@ export function parseCommand(raw: string): ShellCommand {
       return arg ? { type: "skills", name: arg } : { type: "skills" }
     case "features":
       return { type: "features" }
+    case "env":
+      return arg ? { type: "env", name: arg } : { type: "env" }
     case "init":
       return { type: "init" }
     case "rerun":

package/src/config.ts

@@ -1,5 +1,6 @@
 import { setPromptDirs } from "./prompts.ts"
 import { qualityConfig, type QualityConfig } from "./quality/budgets.ts"
+import { containersConfig, type ContainersConfig } from "./containers/config.ts"
 import { existsSync, readFileSync } from "node:fs"
 import os from "node:os"
 import path from "node:path"
@@ -11,6 +12,8 @@ import YAML from "yaml"
 import type { LlmProfile } from "./llm.ts"
 import type { ReplayMode } from "./types.ts"
 import { loadDotEnv } from "./env.ts"
+import { CAPABILITIES } from "./capabilities/registry.ts"
+import { exportEnvironment, loadEnvironments, withEnvironment, type EnvironmentsConfig } from "./environments.ts"
 import { systemLocale } from "./locale.ts"
 import { currencyCode, currencyForLocale } from "./money.ts"
 import { listPrice, pricesDate, type DeploymentType, type ListPrice } from "./prices.ts"
@@ -366,13 +369,28 @@ export type AppConfig = {
   profiles: Record<string, LlmProfile>
   llm: LlmProfile
   browser: BrowserConfig
+  /** `desktop:` in forgeqe.yaml: the Windows apps desktop workflows may start, and the secrets they may type (docs/DESKTOP.md). */
+  desktop: DesktopConfig
   /**
-   * stepInstruction and guiderails are added to the browser agent's prompt. dirs: where edited prompts are looked for,
+   * `agent.capabilities` in forgeqe.yaml: capabilities whose tools ForgeQE's agent always has (always), and ones it never
+   * gets (off). The rest it gets per request (src/mcp/scope.ts).
+   */
+  agentScope: { always: string[]; off: string[] }
+  /** `mobile:` in forgeqe.yaml: Android and iOS apps, Appium or Maestro, and the secrets workflows may type (docs/MOBILE.md). */
+  mobile: MobileConfig
+  /** `containers:` in forgeqe.yaml: services ForgeQE may start in Docker or Podman, and the mocks' image (docs/CONTAINERS.md). */
+  containers?: ContainersConfig
+  /** Test environments from env.yaml (`environments:` in forgeqe.yaml); the active one's desktop and mobile apps are in `desktop` and `mobile`. */
+  environments?: EnvironmentsConfig
+  /**
+   * stepInstruction is added to the browser agent's prompt; guiderails' lines are guardrails for every agent (src/guardrails.ts). dirs: where edited prompts are looked for,
    * highest precedence first (prompts.dir, the project's .forgeqe/prompts, ~/.forgeqe/prompts); see src/prompts.ts.
    */
   prompts: { stepInstruction: string; guiderails: string; dirs?: { dir: string; source: string }[] }
   /** Product knowledge (.forgeqe/knowledge): see src/knowledge.ts. */
   knowledge?: { dir: string; browserMaxChars: number }
+  /** The team's guardrails (.forgeqe/guardrails): see src/guardrails.ts. */
+  guardrails?: { dir: string }
   /** Defect intelligence (defects: in forgeqe.yaml): see src/cases/defects.ts, repro.ts, rca.ts. */
   defects: DefectsConfig
   export: { outDir: string; format: string }
@@ -412,6 +430,122 @@ export type AppConfig = {
   budget?: BudgetConfig
 }
 
+export type DesktopConfig = {
+  /** App name to { path, args, window }; the desktop engine checks each entry (an absolute .exe, an argument list). */
+  apps: Record<string, unknown>
+  /** Environment variables a workflow's {{secret:NAME}} may read; nothing else in the environment reaches the engine. */
+  secrets: string[]
+  /** Replay asks the model for a new locator when a step's control is not found (desktop.heal, default on). */
+  heal: boolean
+  screenshots: boolean
+}
+
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/
+
+function desktopConfig(raw: Record<string, unknown>): DesktopConfig {
+  const secrets = raw.secrets === undefined || raw.secrets === null ? [] : raw.secrets
+  if (!Array.isArray(secrets) || !secrets.every((n) => typeof n === "string" && ENV_NAME.test(n))) {
+    throw new Error("desktop.secrets in forgeqe.yaml must be a list of environment variable names (letters, digits and _).")
+  }
+  return { apps: asRecord(raw.apps), secrets: [...new Set(secrets as string[])], heal: raw.heal !== false, screenshots: raw.screenshots !== false }
+}
+
+export type MobileConfig = {
+  /** App name to { platform, app_id, activity, app }; the mobile engine checks each entry. */
+  apps: Record<string, unknown>
+  /** Environment variables a workflow's {{secret:NAME}} may read. */
+  secrets: string[]
+  /** How workflows replay unless a run says otherwise: appium (step by step, with healing) or maestro. */
+  driver: "appium" | "maestro"
+  appium: {
+    /** The Appium server: the team's own (default http://127.0.0.1:4723) or a device cloud's hub. */
+    url: string
+    /** Extra W3C capabilities (appium:deviceName, appium:udid, appium:platformVersion, a cloud's options). */
+    capabilities: Record<string, unknown>
+    /** A device cloud's user and key, as the names of environment variables. */
+    usernameEnv?: string
+    accessKeyEnv?: string
+  }
+  maestro: {
+    command: string[]
+    device?: string
+    /** Maestro on TestMu AI's devices through HyperExecute, instead of a local maestro. */
+    testmu?: { cli: string; devices: string[]; realDevice: boolean; region?: string; usernameEnv: string; accessKeyEnv: string }
+  }
+  heal: boolean
+  screenshots: boolean
+}
+
+function agentScopeConfig(raw: Record<string, unknown>): AppConfig["agentScope"] {
+  const caps = asRecord(raw.capabilities)
+  const known = new Set(CAPABILITIES.map((c) => c.id))
+  const list = (key: "always" | "off") => {
+    const v = caps[key]
+    if (v === undefined || v === null) return []
+    if (!Array.isArray(v) || !v.every((x) => typeof x === "string" && known.has(x))) {
+      throw new Error(`agent.capabilities.${key} in forgeqe.yaml must list capability ids (${[...known].join(", ")}).`)
+    }
+    return [...new Set(v as string[])]
+  }
+  const always = list("always")
+  const off = list("off")
+  const both = always.filter((c) => off.includes(c))
+  if (both.length) throw new Error(`agent.capabilities: ${both.join(", ")} cannot be both always and off.`)
+  return { always, off }
+}
+
+export function mobileConfig(raw: Record<string, unknown>, base: string = process.cwd()): MobileConfig {
+  const secrets = raw.secrets === undefined || raw.secrets === null ? [] : raw.secrets
+  if (!Array.isArray(secrets) || !secrets.every((n) => typeof n === "string" && ENV_NAME.test(n))) {
+    throw new Error("mobile.secrets in forgeqe.yaml must be a list of environment variable names (letters, digits and _).")
+  }
+  const driver = raw.driver === undefined ? "appium" : raw.driver
+  if (driver !== "appium" && driver !== "maestro") throw new Error("mobile.driver in forgeqe.yaml must be appium or maestro.")
+  const a = asRecord(raw.appium)
+  const url = a.url === undefined ? "http://127.0.0.1:4723" : String(a.url)
+  if (!/^https?:\/\/[^\s]+$/i.test(url)) throw new Error("mobile.appium.url in forgeqe.yaml must be an http(s) URL.")
+  if (/^https?:\/\/[^/]*@/i.test(url)) throw new Error("mobile.appium.url must not hold a user or key: use mobile.appium.username_env and access_key_env.")
+  const envName = (v: unknown, key: string): string | undefined => {
+    if (v === undefined || v === null || v === "") return undefined
+    if (typeof v !== "string" || !ENV_NAME.test(v)) throw new Error(`mobile.appium.${key} must be the name of an environment variable.`)
+    return v
+  }
+  const m = asRecord(raw.maestro)
+  const command = m.command === undefined ? ["maestro"] : Array.isArray(m.command) ? m.command.map(String) : [String(m.command)]
+  if (!command.length || command.some((c) => !c || /[\r\n]/.test(c))) throw new Error("mobile.maestro.command must be the maestro program (and its arguments) as a list.")
+  const device = m.device === undefined ? undefined : String(m.device)
+  if (device !== undefined && !/^[A-Za-z0-9._:-]{1,100}$/.test(device)) throw new Error("mobile.maestro.device must be a device id (adb devices or xcrun simctl list).")
+  const t = m.testmu === undefined || m.testmu === null || m.testmu === false ? undefined : asRecord(m.testmu)
+  let testmu: MobileConfig["maestro"]["testmu"]
+  if (t) {
+    const devices = Array.isArray(t.devices) ? t.devices.map(String) : []
+    if (!devices.length || devices.some((d) => !/^[A-Za-z0-9 ._*()+-]{1,60}$/.test(d))) throw new Error('mobile.maestro.testmu.devices must be a list of TestMu device names, e.g. ["Pixel 6-14"].')
+    const region = t.region === undefined ? undefined : String(t.region)
+    if (region !== undefined && !/^[a-z]{2,4}$/.test(region)) throw new Error("mobile.maestro.testmu.region must be a TestMu region code, e.g. us or ap.")
+    const named = t.cli === undefined ? "hyperexecute" : String(t.cli)
+    if (!named || /[\x00-\x1f]/.test(named)) throw new Error("mobile.maestro.testmu.cli must be the path of the hyperexecute program.")
+    // A path (./hyperexecute) is relative to forgeqe.yaml; a bare name is looked up on PATH.
+    const cli = /[\\/]/.test(named) && !path.isAbsolute(named) ? path.resolve(base, named) : named
+    const tEnv = (v: unknown, key: string, fallback: string) => {
+      const name = v === undefined ? fallback : v
+      if (typeof name !== "string" || !ENV_NAME.test(name)) throw new Error(`mobile.maestro.testmu.${key} must be the name of an environment variable.`)
+      return name
+    }
+    testmu = { cli, devices, realDevice: t.real_device !== false, ...(region ? { region } : {}), usernameEnv: tEnv(t.username_env, "username_env", "LT_USERNAME"), accessKeyEnv: tEnv(t.access_key_env, "access_key_env", "LT_ACCESS_KEY") }
+  }
+  const usernameEnv = envName(a.username_env, "username_env")
+  const accessKeyEnv = envName(a.access_key_env, "access_key_env")
+  return {
+    apps: asRecord(raw.apps),
+    secrets: [...new Set(secrets as string[])],
+    driver,
+    appium: { url, capabilities: asRecord(a.capabilities), ...(usernameEnv ? { usernameEnv } : {}), ...(accessKeyEnv ? { accessKeyEnv } : {}) },
+    maestro: { command, ...(device ? { device } : {}), ...(testmu ? { testmu } : {}) },
+    heal: raw.heal !== false,
+    screenshots: raw.screenshots !== false,
+  }
+}
+
 export type DomainConfig = {
   /** In the team's words, e.g. "retail banking", "property and casualty insurance". */
   industry: string
@@ -681,8 +815,12 @@ function profileFromRaw(name: string, raw: Record<string, unknown>): LlmProfile
     ...(String(raw.auth || "").toLowerCase() === "entra" ? { auth: "entra" as const } : {}),
     managedIdentityClientId: raw.managed_identity_client_id ? String(raw.managed_identity_client_id) : undefined,
     tokenScope: raw.token_scope ? String(raw.token_scope) : undefined,
+    ...(raw.engine_model ? { engineModel: String(raw.engine_model) } : {}),
+    ...(raw.github_org ? { githubOrg: String(raw.github_org) } : {}),
     apiVersion: raw.api_version ? String(raw.api_version) : undefined,
     temperature: typeof raw.temperature === "number" ? raw.temperature : undefined,
+    ...(typeof raw.vision === "boolean" ? { vision: raw.vision } : {}),
+    ...(typeof raw.reasoning === "boolean" ? { reasoning: raw.reasoning } : {}),
     ...priceFor(name, raw, provider, String(raw.model || "gpt-4o")),
   }
 }
@@ -797,7 +935,7 @@ function codeBudget(raw: unknown): number | undefined {
   return n > 0 ? n : undefined
 }
 
-export function loadConfig(opts?: { configPath?: string; profile?: string }): AppConfig {
+export function loadConfig(opts?: { configPath?: string; profile?: string; env?: string }): AppConfig {
   // FORGEQE_CWD_ENV=off: tests never read the .env of the folder they run in (the developer's own keys).
   if (process.env.FORGEQE_CWD_ENV !== "off") loadDotEnv(process.cwd())
   const configPath = findConfigFile(opts?.configPath)
@@ -848,6 +986,10 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
     activeProfile,
     profiles,
     llm: profiles[activeProfile] || { ...NO_PROFILE },
+    desktop: desktopConfig(asRecord(yaml.desktop)),
+    mobile: mobileConfig(asRecord(yaml.mobile), base),
+    containers: containersConfig(asRecord(yaml.containers), base),
+    agentScope: agentScopeConfig(asRecord(yaml.agent)),
     browser: {
       provider,
       headless: browser.headless !== false,
@@ -871,6 +1013,7 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
       dirs: promptDirsFor(prompts, base, configPath),
     },
     knowledge: knowledgeConfig(asRecord(yaml.knowledge), base, configPath),
+    guardrails: guardrailsConfig(asRecord(yaml.guardrails), base, configPath),
     defects: defectsConfig(asRecord(yaml.defects), base),
     export: {
       outDir,
@@ -929,7 +1072,16 @@ export function loadConfig(opts?: { configPath?: string; profile?: string }): Ap
   }
   // Prompts resolve from these folders from now on (src/prompts.ts).
   setPromptDirs(config.prompts.dirs || [])
-  return config
+  const environments = loadEnvironments(asRecord(yaml.environments), base, config.desktop, opts?.env || process.env.FORGEQE_ENV || undefined, config.browser.allowedHosts, {
+    startUrl: config.browser.startUrl,
+    apiUrl: config.api?.baseUrl,
+    mobile: config.mobile,
+  })
+  if (!environments) return config
+  const withEnv = withEnvironment({ ...config, environments })
+  // Tests and agents ForgeQE starts read the environment from FORGEQE_ACTIVE_ENV and FORGEQE_APP_* (src/environments.ts).
+  exportEnvironment(withEnv)
+  return withEnv
 }
 
 function skillsConfig(raw: unknown, base: string): SkillsConfig {
@@ -1187,6 +1339,10 @@ export function defectsConfig(d: Record<string, unknown>, base: string): Defects
   }
 }
 
+function guardrailsConfig(g: Record<string, unknown>, base: string, configPath: string | undefined): NonNullable<AppConfig["guardrails"]> {
+  return { dir: g.dir ? path.resolve(base, String(g.dir)) : configPath ? path.join(projectDir(base), "guardrails") : path.join(forgeqeHome(), "guardrails") }
+}
+
 function knowledgeConfig(k: Record<string, unknown>, base: string, configPath: string | undefined): NonNullable<AppConfig["knowledge"]> {
   const dir = k.dir ? path.resolve(base, String(k.dir)) : configPath ? path.join(projectDir(base), "knowledge") : path.join(forgeqeHome(), "knowledge")
   const max = Number(k.browser_max_chars)

package/src/containers/command.ts

@@ -0,0 +1,68 @@
+import { configOpts, strFlag, type Flags } from "../cli/args.ts"
+import { loadConfig } from "../config.ts"
+import { containersOf, startOrder } from "./config.ts"
+import { findRuntime, listContainers, runtimeVersion, serviceLogs, spawnExec, startService, stopServices, type Ctx } from "./run.ts"
+
+/** `forgeqe services`: the project's services in Docker or Podman (docs/CONTAINERS.md). */
+
+export const SERVICES_USAGE = `Usage:
+  forgeqe services [status]                 the declared services, what runs, and whether Docker or Podman answers
+  forgeqe services up [name ...]            start services (default: all) and wait until each is ready; they keep
+                                            running after this command, until forgeqe services down
+  forgeqe services down [name ...]          stop and remove this project's containers (default: all, mocks included)
+  forgeqe services logs <name> [--lines N]  a service's last lines, secrets removed`
+
+export async function cmdServices(args: string[], flags: Flags): Promise<number> {
+  const cfg = loadConfig(configOpts(flags))
+  const [op = "status", ...names] = args
+  const declared = containersOf(cfg).services
+  const runtime = findRuntime(cfg)
+  if (!runtime) {
+    console.error(`${containersOf(cfg).runtime || "Docker or Podman"} is not on PATH. Install Docker Desktop, Docker Engine or Podman.`)
+    return 1
+  }
+  const ctx: Ctx = { cfg, runtime, exec: spawnExec, log: (t) => console.log(t) }
+  if (op === "status") {
+    const v = await runtimeVersion(ctx)
+    console.log(v.ok ? `${runtime.name} ${v.version}` : `${runtime.name} does not answer: ${v.error}`)
+    const rows = v.ok ? await listContainers(ctx) : []
+    const names = Object.keys(declared)
+    console.log(names.length ? `Declared: ${names.map((n) => `${n} (${declared[n]!.image})`).join(", ")}` : "No services declared (containers.services in forgeqe.yaml).")
+    for (const r of rows) console.log(`  ${r.service.padEnd(24)} ${r.state.padEnd(10)} ${r.ports || ""}`)
+    if (v.ok && !rows.length) console.log("Nothing of this project is running.")
+    return v.ok ? 0 : 1
+  }
+  const unknown = names.filter((n) => !declared[n] && !(op !== "up" && n.startsWith("mock-")))
+  if (unknown.length) {
+    console.error(`Not declared in forgeqe.yaml containers.services: ${unknown.join(", ")} (declared: ${Object.keys(declared).join(", ") || "none"}).`)
+    return 1
+  }
+  if (op === "up") {
+    const specs = startOrder(declared, names)
+    if (!specs.length) {
+      console.error("No services declared: add them under containers.services in forgeqe.yaml (docs/CONTAINERS.md).")
+      return 1
+    }
+    for (const s of specs) {
+      const r = await startService(ctx, s, { keep: true })
+      if (!r.ready) {
+        console.error(`✗ ${s.name}: ${r.error}${r.logs ? `\n${r.logs}` : ""}`)
+        return 1
+      }
+      console.log(`✓ ${s.name} ready${r.ports.length ? ` on ${r.ports.map((p) => p.address).join(", ")}` : ""} (${(r.ms / 1000).toFixed(1)} s)`)
+    }
+    return 0
+  }
+  if (op === "down") {
+    const stopped = await stopServices(ctx, names.length ? names : undefined)
+    console.log(stopped.length ? `Stopped ${stopped.join(", ")}.` : "Nothing of this project was running.")
+    return 0
+  }
+  if (op === "logs") {
+    if (names.length !== 1) throw new Error(SERVICES_USAGE)
+    const lines = strFlag(flags, "lines")
+    console.log(await serviceLogs(ctx, names[0]!, lines ? Number(lines) : 100))
+    return 0
+  }
+  throw new Error(SERVICES_USAGE)
+}