@saadnvd1/agent-os 0.3.659 → 0.3.662

package/app/api/sessions/[id]/summarize/route.ts

@@ -8,6 +8,7 @@ import { randomUUID } from "crypto";
 import { readFile } from "fs/promises";
 import { homedir } from "os";
 import { pasteText, tmux } from "@/lib/tmux/exec";
+import { sessionBaseEnv, UNSET_SERVER_ENV } from "@/lib/agents/server-env";
 
 // Get Claude session ID from tmux environment
 async function getClaudeSessionId(tmuxSession: string): Promise<string | null> {
@@ -135,7 +136,7 @@ async function generateSummary(conversation: string): Promise<string> {
   const routed = await routedRun("helper");
   return new Promise((resolve, reject) => {
     const claude = spawn("claude", ["-p", prompt, "--model", routed.model], {
-      env: { ...process.env, ...routed.env },
+      env: { ...sessionBaseEnv(), ...routed.env },
       stdio: ["pipe", "pipe", "pipe"],
     });
 
@@ -309,7 +310,7 @@ export async function POST(
 
       // Start new tmux session with Claude directly
       const isRoot = process.getuid?.() === 0;
-      const envPrefix = isRoot ? "IS_SANDBOX=1 " : "";
+      const envPrefix = UNSET_SERVER_ENV + (isRoot ? "IS_SANDBOX=1 " : "");
       const claudeCmd = effectiveAutoApprove(session.auto_approve)
         ? `${envPrefix}claude --dangerously-skip-permissions`
         : "claude";

package/lib/agents/launch.ts

@@ -10,6 +10,7 @@ import { runInBackground } from "../async-operations";
 import { trustPromptKeys } from "../tasks/state";
 import { BUS_BRIEF } from "./brief";
 import { selfUrl } from "./self-env";
+import { sessionBaseEnv, UNSET_SERVER_ENV } from "./server-env";
 import { sessionPath } from "./tool-path";
 import { autoCompactEnv } from "../chat/refresh";
 import { subagentEnv } from "../models/subagents";
@@ -110,7 +111,7 @@ export async function launchClaude(opts: {
     model_provider: opts.provider ?? null,
   });
   const mcpFlags = routedMcpFlags(opts.provider);
-  const agent = `export PATH=${shellQuote(AOS_BIN_DIR)}:"$HOME/.local/bin:$PATH"; ${routing.exportKey} ${provider.command} ${flags} ${mcpFlags}${CLAUDE_STATUS_SETTINGS_FLAG} --append-system-prompt-file ${shellQuote(briefFile)} "$(cat ${shellQuote(promptFile)})"; exec "\${SHELL:-/bin/sh}" -l`;
+  const agent = `${UNSET_SERVER_ENV}export PATH=${shellQuote(AOS_BIN_DIR)}:"$HOME/.local/bin:$PATH"; ${routing.exportKey} ${provider.command} ${flags} ${mcpFlags}${CLAUDE_STATUS_SETTINGS_FLAG} --append-system-prompt-file ${shellQuote(briefFile)} "$(cat ${shellQuote(promptFile)})"; exec "\${SHELL:-/bin/sh}" -l`;
   await execFileAsync(
     "tmux",
     [
@@ -123,7 +124,7 @@ export async function launchClaude(opts: {
       ...envArgs({ ...agentEnv(opts.sessionId), ...routing.env }),
       agent,
     ],
-    { cwd: opts.cwd }
+    { cwd: opts.cwd, env: sessionBaseEnv() }
   );
   runInBackground(
     () => acceptTrustPrompt(opts.tmuxName),

package/lib/agents/server-env.ts

@@ -0,0 +1,24 @@
+// Variables the server sets only for itself (`npm start`, `npm run dev`,
+// the dev-instance spawner). A session that inherits them breaks the
+// project it works in: NODE_ENV=production makes Vitest load React's
+// production build, PORT makes a dev server bind the live one's port.
+// AGENTOS_URL, AGENTOS_PORT and the session ids are not here: sessions need them.
+export const SERVER_ONLY_ENV = [
+  "NODE_ENV",
+  "PORT",
+  "AGENTOS_SERVER",
+  "AGENTOS_DEV",
+] as const;
+
+// Shell text that clears them inside a pane. `tmux new-session -e` can only
+// add variables, and an already-running tmux server may hold them globally.
+export const UNSET_SERVER_ENV = `unset ${SERVER_ONLY_ENV.join(" ")}; `;
+
+// The server's environment as an agent or its tools should see it.
+export function sessionBaseEnv(
+  env: NodeJS.ProcessEnv = process.env
+): NodeJS.ProcessEnv {
+  const out = { ...env };
+  for (const k of SERVER_ONLY_ENV) delete out[k];
+  return out;
+}

package/lib/chat/drivers/claude.ts

@@ -1,3 +1,4 @@
+import { sessionBaseEnv } from "../../agents/server-env";
 import { randomUUID } from "crypto";
 import {
   getSessionMessages,
@@ -145,7 +146,7 @@ export const claudeDriver: ChatDriver = {
         cwd,
         permissionMode: "bypassPermissions",
         allowDangerouslySkipPermissions: true,
-        env: { ...process.env, ...env },
+        env: { ...sessionBaseEnv(), ...env },
       },
     });
     try {
@@ -235,7 +236,7 @@ export const claudeDriver: ChatDriver = {
           append: options.systemAppend,
         },
         env: {
-          ...process.env,
+          ...sessionBaseEnv(),
           ...options.env,
           // When the agent is done with every turn it had queued: the end
           // of a turn that never sent its result.

package/lib/chat/drivers/codex.ts

@@ -1,3 +1,4 @@
+import { sessionBaseEnv } from "../../agents/server-env";
 import type { ChatConversation, ChatDriver } from "../driver";
 import type { ChatImage, DriverEvent } from "../events";
 import { InputQueue } from "../queue";
@@ -16,7 +17,7 @@ export const codexDriver: ChatDriver = {
 
   async discover({ cwd, env }) {
     const rpc = new CodexRpc(
-      { cwd, env: { ...process.env, ...env } },
+      { cwd, env: { ...sessionBaseEnv(), ...env } },
       { notify: () => {}, request: () => {}, exit: () => {} }
     );
     try {
@@ -51,7 +52,7 @@ export const codexDriver: ChatDriver = {
     let starting = false;
     let stopOnStart = false;
     const rpc: CodexRpc = new CodexRpc(
-      { cwd: options.cwd, env: { ...process.env, ...options.env } },
+      { cwd: options.cwd, env: { ...sessionBaseEnv(), ...options.env } },
       {
         notify(method, params) {
           if (method === "item/started") approvals.sawItem(params.item as P);

package/lib/chat/drivers/copilot.ts

@@ -1,3 +1,4 @@
+import { sessionBaseEnv } from "../../agents/server-env";
 import type { ChatConversation, ChatDriver, ChatStartOptions } from "../driver";
 import type { ChatImage, DriverEvent } from "../events";
 import { InputQueue } from "../queue";
@@ -52,7 +53,7 @@ export const copilotDriver: ChatDriver = {
     const held: { text: string; images?: ChatImage[] }[] = [];
     const rpc: CopilotRpc = new CopilotRpc(
       copilotArgs(options),
-      { cwd: options.cwd, env: { ...process.env, ...options.env } },
+      { cwd: options.cwd, env: { ...sessionBaseEnv(), ...options.env } },
       {
         notify(method, params) {
           if (method === "session/update")

package/lib/chat/drivers/opencode.ts

@@ -1,3 +1,4 @@
+import { sessionBaseEnv } from "../../agents/server-env";
 import type { ChatConversation, ChatDriver } from "../driver";
 import type { ChatImage, DriverEvent } from "../events";
 import { InputQueue } from "../queue";
@@ -46,7 +47,7 @@ export const openCodeDriver: ChatDriver = {
   atRest: false,
 
   async discover({ cwd, env }) {
-    const server = new OpenCodeServer(cwd, { ...process.env, ...env });
+    const server = new OpenCodeServer(cwd, { ...sessionBaseEnv(), ...env });
     try {
       const [providers, commands] = await Promise.all([
         server.call<{ all: P[]; connected: string[] }>("GET", "/provider"),
@@ -79,7 +80,7 @@ export const openCodeDriver: ChatDriver = {
     const out = new InputQueue<DriverEvent>();
     const emit = (e: DriverEvent) => out.push(e);
     const server = new OpenCodeServer(options.cwd, {
-      ...process.env,
+      ...sessionBaseEnv(),
       ...options.env,
     });
     let sessionId: string | null = null;

package/lib/chat/drivers/pi.ts

@@ -1,3 +1,4 @@
+import { sessionBaseEnv } from "../../agents/server-env";
 import type { ChatConversation, ChatDriver, ChatStartOptions } from "../driver";
 import type { ChatImage, DriverEvent } from "../events";
 import { InputQueue } from "../queue";
@@ -45,7 +46,7 @@ export const piDriver: ChatDriver = {
   async discover({ cwd, env }) {
     const rpc = new PiRpc(
       ["--no-session", "--offline"],
-      { cwd, env: { ...process.env, ...env } },
+      { cwd, env: { ...sessionBaseEnv(), ...env } },
       { event: () => {}, ui: () => {}, exit: () => {} }
     );
     try {
@@ -82,7 +83,7 @@ export const piDriver: ChatDriver = {
       {
         cwd: options.cwd,
         env: {
-          ...process.env,
+          ...sessionBaseEnv(),
           ...options.env,
           AGENTOS_PI_ACCESS_FILE: access.file,
           PI_OFFLINE: "1",

package/lib/chat/worker/client.ts

@@ -1,3 +1,4 @@
+import { UNSET_SERVER_ENV, sessionBaseEnv } from "../../agents/server-env";
 /**
  * The server's side of a chat worker: starts one in tmux when none is
  * running, connects to its socket, and passes commands and events along.
@@ -224,7 +225,7 @@ async function spawnWorker(sessionId: string): Promise<void> {
   if (await tmuxHas(name)) return;
   fs.mkdirSync(workerDir(), { recursive: true, mode: 0o700 });
   const env: Record<string, string | undefined> = {
-    ...process.env,
+    ...sessionBaseEnv(),
     DB_PATH: path.resolve(
       process.env.DB_PATH || path.join(process.cwd(), "agent-os.db")
     ),
@@ -233,18 +234,22 @@ async function spawnWorker(sessionId: string): Promise<void> {
   delete env.TMUX_PANE;
   fs.writeFileSync(envPath(sessionId), JSON.stringify(env), { mode: 0o600 });
   const entry = path.join(process.cwd(), "lib/chat/worker/main.ts");
-  await execFileAsync("tmux", [
-    "new-session",
-    "-d",
-    "-s",
-    name,
-    "-c",
-    process.cwd(),
-    // The worker finds its env file by DB_PATH, so it can't come from there.
-    "-e",
-    `DB_PATH=${env.DB_PATH}`,
-    `exec ${shellQuote(process.execPath)} --import tsx ${shellQuote(entry)} ${shellQuote(sessionId)} > ${shellQuote(path.join(workerDir(), `${sessionId}.log`))} 2>&1`,
-  ]);
+  await execFileAsync(
+    "tmux",
+    [
+      "new-session",
+      "-d",
+      "-s",
+      name,
+      "-c",
+      process.cwd(),
+      // The worker finds its env file by DB_PATH, so it can't come from there.
+      "-e",
+      `DB_PATH=${env.DB_PATH}`,
+      `${UNSET_SERVER_ENV}exec ${shellQuote(process.execPath)} --import tsx ${shellQuote(entry)} ${shellQuote(sessionId)} > ${shellQuote(path.join(workerDir(), `${sessionId}.log`))} 2>&1`,
+    ],
+    { env: sessionBaseEnv() }
+  );
 }
 
 const shellQuote = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`;

package/lib/hosts/attach.ts

@@ -1,5 +1,12 @@
 import { SSH_OPTIONS, loginShellCommand, shellQuote } from "./ssh";
 import { isValidTmuxName } from "./tmux-name";
+import { SERVER_ONLY_ENV } from "../agents/server-env";
+
+// For a shared tmux server that already holds them: attach is the one path
+// that cannot prefix the pane command.
+const UNSET_GLOBAL_ENV = SERVER_ONLY_ENV.map(
+  (k) => `set-environment -gu ${k} \\;`
+).join(" ");
 
 export interface AttachSpec {
   sessionName: string;
@@ -28,7 +35,7 @@ export function buildTmuxAttachCommand(spec: AttachSpec): string {
   }
   // Commands chained after an attaching command only run once the client
   // detaches, so options go first; start-server keeps a fresh server alive.
-  const prefix = "tmux start-server \\; set -g mouse on \\;";
+  const prefix = `tmux start-server \\; set -g mouse on \\; ${UNSET_GLOBAL_ENV}`;
   if (spec.attachOnly) {
     // Quoted: zsh expands a bare "=word" to a command path.
     return `${prefix} attach-session -t ${shellQuote(`=${spec.sessionName}`)}`;

package/lib/orchestration.ts

@@ -15,6 +15,7 @@ import { resolveModelForAgent } from "./model-catalog";
 import { type AgentType, getProvider } from "./providers";
 import { statusDetector } from "./status-detector";
 import { wrapWithBanner } from "./banner";
+import { UNSET_SERVER_ENV } from "./agents/server-env";
 import { runInBackground } from "./async-operations";
 import { tmux } from "./tmux/exec";
 import { endTmuxSession } from "./tmux/end";
@@ -168,7 +169,8 @@ export async function spawnWorker(
 
   // Create tmux session with the agent and banner
   const agentCmd = `${provider.command} ${flagsStr}`;
-  const newSessionCmd = wrapWithBanner(agentCmd, provider.preamble);
+  const newSessionCmd =
+    UNSET_SERVER_ENV + wrapWithBanner(agentCmd, provider.preamble);
   try {
     await tmux(["set", "-g", "mouse", "on"]).catch(() => {});
     // The last argument is the agent's command line, which tmux runs.

package/lib/orchestrator/external-gates.ts

@@ -10,6 +10,7 @@
  * does carry is held to the same rules as a task's.
  */
 
+import { hasUiEvidence } from "../tasks/ui-change";
 import { MERGED_AS, mergePolicy } from "../tasks/merge-policy";
 import { mergePR } from "../tasks/merge-pr";
 import { attributionIn, codeReviewGate } from "../tasks/code-review";
@@ -171,7 +172,11 @@ export async function reviewExternal(
       goal: `${ext.title}\n\n${ext.body}`.slice(0, GOAL_CAP),
       repo: ext.repo,
       refs: refsOf(ext),
-      pr: { number: ext.number, url: ext.url },
+      pr: {
+        number: ext.number,
+        url: ext.url,
+        uiEvidence: hasUiEvidence(ext.body),
+      },
     },
     ext.pr.head,
     opts

package/lib/orchestrator/review-prompt.ts

@@ -7,7 +7,7 @@ import type { ChangedFile } from "./diff";
 
 export const REVIEW_SYSTEM = `You are an independent code reviewer. You did not write this change and you owe its author nothing. You review one pull request at one exact commit, checked out read-only in your working directory. You can read the checkout's files; you cannot edit anything or run commands.
 
-Look for what would be wrong if this merged: bugs, broken behaviour, missing error handling on real paths, security problems (secrets, injection, unsafe shell or SQL), data loss, and changes that don't do what the task asked. Style and taste are never blocking.
+Look for what would be wrong if this merged: bugs, broken behaviour, missing error handling on real paths, security problems (secrets, injection, unsafe shell or SQL), data loss, and changes that don't do what the task asked. Style and taste are never blocking, and neither is a missing screenshot or browser or simulator check: AgentOS notes that itself.
 
 A change that games a gate instead of passing it is always blocking: tests deleted, skipped or weakened, assertions loosened or changed to match wrong output, checks, lint rules or CI steps disabled or bypassed, or anything else that makes a failure stop showing rather than stop happening. Name what was weakened, at its file and line.
 

package/lib/orchestrator/review.ts

@@ -11,6 +11,7 @@
  * the orchestrator hears the verdict as an event.
  */
 
+import { uiEvidenceNote, withUiEvidenceNote } from "../tasks/ui-change";
 import { reviewGoal } from "../plans/features";
 import { pushReviewBlocked, pushReviewReady } from "../notify/push/events";
 import { db, type Session } from "../db";
@@ -89,7 +90,7 @@ export interface ReviewTarget {
   goal: string;
   repo: string;
   refs: Pick<Session, "base_branch" | "branch_name">;
-  pr: Pick<TaskPR, "number" | "url" | "scopeChange">;
+  pr: Pick<TaskPR, "number" | "url" | "scopeChange" | "uiEvidence">;
   task?: Session;
 }
 
@@ -192,7 +193,10 @@ async function reviewJob(
     const done = putCheck({
       ...row,
       kind: "review",
-      ...combineVerdicts(verdicts),
+      ...withUiEvidenceNote(
+        combineVerdicts(verdicts),
+        uiEvidenceNote(files, pr.uiEvidence)
+      ),
     });
     if (task?.lh_card_id)
       await checkScope({

package/lib/pr-generation.ts

@@ -1,3 +1,4 @@
+import { sessionBaseEnv } from "./agents/server-env";
 import { routedRun } from "./models/launch";
 import { execFile } from "child_process";
 import { git as runGit } from "./git-exec";
@@ -163,7 +164,7 @@ async function claudePrint(cwd: string, prompt: string): Promise<string> {
       ["--print", "--model", routed.model],
       {
         cwd,
-        env: { ...process.env, ...routed.env },
+        env: { ...sessionBaseEnv(), ...routed.env },
         encoding: "utf-8",
         timeout: 30_000,
         killSignal: "SIGKILL",

package/lib/project-config/agentos.schema.json

@@ -142,6 +142,31 @@
         "port": {
           "type": "string",
           "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+        },
+        "viewports": {
+          "minItems": 1,
+          "maxItems": 4,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^\\d{3,4}x\\d{3,4}$"
+          }
+        },
+        "nav": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 40
+          },
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          }
+        },
+        "verify": {
+          "type": "boolean"
         }
       },
       "additionalProperties": false

package/lib/project-config/brief.ts

@@ -50,6 +50,20 @@ export function runningBrief(
     lines.push(
       `- \`${browse.map}\` maps every page to its URL: navigate by URL, don't explore.`
     );
+  const pages = Object.entries(browse?.nav ?? {});
+  if (pages.length)
+    lines.push(
+      `- Pages: ${pages
+        .map(([name, to]) => {
+          const url = /^https?:\/\//.test(to)
+            ? to
+            : port
+              ? `http://localhost:${port}${to.startsWith("/") ? "" : "/"}${to}`
+              : to;
+          return `${name} \`${withPorts(url, ports)}\``;
+        })
+        .join(", ")}.`
+    );
   if (browse)
     lines.push(
       "- Check state with the browser's text snapshot, not screenshots. Screenshot only the final changed screen, and just the changed element (its uid) rather than the full page where the tool allows; every image stays in your context."

package/lib/project-config/index.ts

@@ -200,3 +200,9 @@ export function projectEnv(
     env[name] = String(port);
   return env;
 }
+
+export const DEFAULT_VIEWPORTS = ["1440x900", "390x844"];
+
+// The sizes a UI change is checked at: the project's, else desktop and phone.
+export const viewportsOf = (browse: ProjectConfig["browse"]): string[] =>
+  browse?.viewports?.length ? browse.viewports : DEFAULT_VIEWPORTS;

package/lib/project-config/schema.ts

@@ -67,6 +67,27 @@ const browse = z.strictObject({
   login: z.string().min(1).optional(),
   map: projectPath.optional(),
   port: envName.optional(),
+  // Screen sizes a UI change is checked at, "WIDTHxHEIGHT".
+  viewports: z
+    .array(
+      z
+        .string()
+        .regex(/^\d{3,4}x\d{3,4}$/, "must be WIDTHxHEIGHT, like 390x844")
+    )
+    .min(1)
+    .max(4)
+    .optional(),
+  // A short page name to path map, for the pages worth knowing by heart.
+  nav: z
+    .record(z.string().min(1).max(40), z.string().min(1).max(200))
+    .refine(
+      (n) => Object.keys(n).length <= 15,
+      "at most 15 pages; use map for more"
+    )
+    .optional(),
+  // Force the browser-check section of a task's brief on or off; otherwise
+  // the project's files decide (lib/tasks/ui-brief.ts).
+  verify: z.boolean().optional(),
 });
 
 // An iOS simulator tasks may drive on a Mac (lib/simulator). `start` runs in

package/lib/resurrect/index.ts

@@ -33,7 +33,7 @@ import {
   transcriptPath,
   writeTranscript,
 } from "../tasks/transcript";
-import { buildTaskBrief, declaredTest } from "../tasks/brief";
+import { buildTaskBrief, briefFacts } from "../tasks/brief";
 import { syncTaskCardInBackground } from "../lumifyhub/task-cards";
 import { allocatePorts } from "../ports";
 import { loadProjectConfig, portBases } from "../project-config";
@@ -440,7 +440,7 @@ async function relaunch(s: Session, cwd: string): Promise<void> {
       ? buildTaskBrief({
           branch: s.branch_name,
           baseBranch: s.base_branch ?? "main",
-          test: declaredTest(cwd),
+          ...briefFacts(cwd),
         })
       : undefined,
   });

package/lib/tasks/brief.ts

@@ -1,4 +1,5 @@
-import { loadProjectConfig } from "../project-config";
+import { loadProjectConfig, type ProjectConfig } from "../project-config";
+import { uiKindOf, uiVerifyBrief, type UiKind } from "./ui-brief";
 
 // A task stacked on another task's unmerged branch.
 export interface StackedOn {
@@ -21,9 +22,18 @@ function stackedLines(baseBranch: string, stack: StackedOn): string {
 - Never merge or rebase onto the default branch yourself. When the parent merges, AgentOS rebases your branch and retargets your PR, then tells you; re-run your checks when it does. AgentOS reviews your PR itself; a review of your head still counts for the head its restack left, and a push after that gets a new one.${also}`;
 }
 
-// The project's declared test command, read from the checkout the task runs in.
-export function declaredTest(cwd: string): string | undefined {
-  return loadProjectConfig(cwd).config.test || undefined;
+// What a brief needs from the checkout's config, from one read.
+export function briefFacts(cwd: string): {
+  test?: string;
+  ui: UiKind | null;
+  browse: ProjectConfig["browse"];
+} {
+  const { config } = loadProjectConfig(cwd);
+  return {
+    test: config.test || undefined,
+    ui: uiKindOf(cwd, config),
+    browse: config.browse,
+  };
 }
 
 function checksLine(test?: string): string {
@@ -40,8 +50,11 @@ export function buildTaskBrief(opts: {
   stack?: StackedOn;
   // The project's `test` from agentos.json, when it declares one.
   test?: string;
+  // Whether the project has a UI to check, and how it is browsed.
+  ui?: UiKind | null;
+  browse?: ProjectConfig["browse"];
 }): string {
-  return `You are running as an AgentOS background task, alone, in an isolated git worktree.
+  const base = `You are running as an AgentOS background task, alone, in an isolated git worktree.
 
 - Branch: ${opts.branch} (based on ${opts.baseBranch}). Stay in this directory and on this branch.
 - Do the task fully. ${checksLine(opts.test)}
@@ -51,4 +64,6 @@ export function buildTaskBrief(opts: {
 - Write scratch files (PR bodies, review notes, logs, test output) outside the worktree, in your scratchpad or \$TMPDIR. Anything uncommitted left in the worktree keeps it from being removed when the task is done.
 - Do not add any AI or assistant attribution to commits or the pull request.
 - If you are blocked or need a decision only a human can make, print one line starting with "BLOCKED:" that says what you need, then stop and wait.`;
+  const ui = uiVerifyBrief(opts.ui ?? null, opts.browse);
+  return ui ? `${base}\n\n${ui}` : base;
 }

package/lib/tasks/gh.ts

@@ -1,4 +1,5 @@
 import { execFile } from "child_process";
+import { hasUiEvidence } from "./ui-change";
 import { promisify } from "util";
 import { git } from "../git-exec";
 import { attributionIn } from "./code-review";
@@ -118,6 +119,7 @@ export async function toTaskPR(repoDir: string, pr: ListedPR): Promise<TaskPR> {
     attribution:
       pr.body === undefined ? undefined : (attributionIn(pr.body) ?? null),
     scopeChange: parseScopeChange(pr.body),
+    ...(pr.body !== undefined && { uiEvidence: hasUiEvidence(pr.body) }),
     ...(pr.mergeable && { mergeable: pr.mergeable }),
     ...(pr.baseRefName && { base: pr.baseRefName }),
   };

package/lib/tasks/import.ts

@@ -23,7 +23,7 @@ import { resolveModelForAgent } from "../model-catalog";
 import { providerFor } from "../models/resolve";
 import { preparePlanDir, PLAN_FILE } from "../models/plan-step";
 import { carryTaskState } from "./move-carry";
-import { buildTaskBrief, declaredTest } from "./brief";
+import { buildTaskBrief, briefFacts } from "./brief";
 import { expandHome } from "./session";
 import { ensureProject } from "./project-ref";
 import { checkoutBranchWorktree } from "./branch-worktree";
@@ -141,7 +141,7 @@ async function arrive(
   const brief = buildTaskBrief({
     branch: bundle.branch,
     baseBranch,
-    test: declaredTest(worktreePath),
+    ...briefFacts(worktreePath),
   });
   // Checked and written with no await between, so two can't both pass.
   db.transaction(() => {

package/lib/tasks/index.ts

@@ -33,7 +33,7 @@ import { agentLabel } from "../agent-options";
 import { supportsChat } from "../chat/capabilities";
 import { AGENT_DEFAULT_MODEL } from "../providers/registry";
 import { statusDetector } from "../status-detector";
-import { buildTaskBrief, declaredTest, type StackedOn } from "./brief";
+import { buildTaskBrief, briefFacts, type StackedOn } from "./brief";
 import {
   attachTaskCard,
   inBackground,
@@ -382,7 +382,7 @@ async function startTask(
         branch: wt.branchName,
         baseBranch,
         stack: opts.base?.stack,
-        test: declaredTest(wt.worktreePath),
+        ...briefFacts(wt.worktreePath),
       }),
       task_status: "running",
       model_overrides: routing.override

package/lib/tasks/move.ts

@@ -13,7 +13,7 @@ import { db, type Session } from "../db";
 import { getProject } from "../projects";
 import { endTmuxSession } from "../tmux/end";
 import { launchClaude } from "../agents/launch";
-import { buildTaskBrief, declaredTest } from "./brief";
+import { buildTaskBrief, briefFacts } from "./brief";
 import { git as runGit } from "../git-exec";
 import { getTaskSession, isoUTC } from "./session";
 import { projectRef } from "./project-ref";
@@ -309,7 +309,7 @@ async function relaunch(session: Session, note?: string): Promise<void> {
       ? buildTaskBrief({
           branch: session.branch_name,
           baseBranch: session.base_branch ?? "main",
-          test: declaredTest(session.working_directory),
+          ...briefFacts(session.working_directory),
         })
       : undefined,
   });

package/lib/tasks/state.ts

@@ -27,6 +27,9 @@ export interface TaskPR {
   attribution?: AttributionKind | null;
   // The body's "Scope change" note (tasks/scope-change.ts), when it has one.
   scopeChange?: string | null;
+  // Whether the body shows a browser or simulator check (tasks/ui-change.ts);
+  // undefined when the body wasn't read.
+  uiEvidence?: boolean;
   // GitHub's word on merging it into its base: CONFLICTING once the base
   // moved under it (UNKNOWN while GitHub works it out).
   mergeable?: "MERGEABLE" | "CONFLICTING" | "UNKNOWN";

package/lib/tasks/ui-brief.ts

@@ -0,0 +1,85 @@
+// The browser-check section of a task's brief, ported from dispatch's
+// browser_brief. A project's files decide whether a task gets it, not the
+// prompt: the PRs that skipped a check were ones whose prompt never said UI.
+
+import * as fs from "fs";
+import * as path from "path";
+import { viewportsOf } from "../project-config";
+import type { ProjectConfig } from "../project-config";
+
+export type UiKind = "web" | "simulator";
+
+const WEB_DEPS = [
+  "react",
+  "next",
+  "vue",
+  "nuxt",
+  "svelte",
+  "@sveltejs/kit",
+  "astro",
+  "solid-js",
+  "preact",
+  "@angular/core",
+];
+const NATIVE_DEPS = ["react-native", "expo"];
+
+function deps(cwd: string): Set<string> {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(cwd, "package.json"), "utf8")
+    );
+    return new Set([
+      ...Object.keys(pkg.dependencies ?? {}),
+      ...Object.keys(pkg.devDependencies ?? {}),
+    ]);
+  } catch {
+    return new Set();
+  }
+}
+
+function isRailsApp(cwd: string): boolean {
+  try {
+    return (
+      /^\s*gem\s+["']rails["']/m.test(
+        fs.readFileSync(path.join(cwd, "Gemfile"), "utf8")
+      ) && fs.statSync(path.join(cwd, "app", "views")).isDirectory()
+    );
+  } catch {
+    return false;
+  }
+}
+
+// Deterministic and cheap: the config, then two small file reads.
+export function uiKindOf(cwd: string, config: ProjectConfig): UiKind | null {
+  if (config.browse?.verify === false) return null;
+  if (config.simulator) return "simulator";
+  if (config.browse) return "web";
+  const have = deps(cwd);
+  if (NATIVE_DEPS.some((d) => have.has(d))) return null;
+  if (WEB_DEPS.some((d) => have.has(d)) || isRailsApp(cwd)) return "web";
+  return null;
+}
+
+export const SCREENSHOT_DIR = ".agentos/screenshots";
+
+export function uiVerifyBrief(
+  kind: UiKind | null,
+  browse?: ProjectConfig["browse"]
+): string {
+  if (!kind) return "";
+  if (kind === "simulator")
+    return `## Checking UI changes
+
+If your diff changes what a user sees, check the changed screens in the iOS simulator, as "Running this project" describes, before calling it done. Fix anything visibly off. Add a **Simulator check** section to the PR body: the screens you checked, what you looked for, and the screenshot names. If you didn't check, say why in one line.`;
+  const sizes = viewportsOf(browse).join(" and ");
+  return `## Checking UI changes
+
+If your diff changes what a user sees, run the app and look at every changed screen in a real browser before calling it done, at ${sizes} (\`resize_page\` between them). Do it cheaply:
+
+- The browser is the **\`chrome-devtools\`** MCP server. Load \`mcp__chrome-devtools__new_page\`, \`navigate_page\`, \`resize_page\`, \`take_snapshot\`, \`take_screenshot\` and \`evaluate_script\` with ToolSearch. Don't load or call \`mcp__claude-in-chrome__*\`: it isn't configured here and its first call hangs for 30 seconds. If no \`chrome-devtools\` server is available, say so in the PR and describe what you checked instead.
+- Log in and go to pages by URL, from the login, pages and map under "Running this project" when they are there. Exploring the UI to find a page is the most expensive thing a session does.
+- One snapshot to find a uid, then act. Verify with a screenshot of the one element or a small \`evaluate_script\` returning the one value you need, not another full snapshot.
+- Verify the thing that would be wrong, not the thing that is easy to see: a page that rendered proves it rendered. Fix anything visibly off (gaps, clipping, overlap, horizontal scroll, stray bands, misalignment; measure rects with \`evaluate_script\` and report numbers) and read the console for errors.
+- Save screenshots of the final changed screens with \`filePath\` under \`${SCREENSHOT_DIR}/\`, after \`mkdir -p ${SCREENSHOT_DIR} && printf '*\\n' > .agentos/.gitignore\`. That folder is inside the browser's allowed root and git ignores it; a path in /tmp is refused.
+- Add a **Browser check** section to the PR body: the pages and widths you checked, what you fixed, and the screenshot file names. If you didn't check (no visible change, or no browser), say why in one line.`;
+}

package/lib/tasks/ui-change.ts

@@ -0,0 +1,57 @@
+// Whether a change touches what a user sees, and whether its PR body shows
+// anyone looked. The note it makes is for the reviewer's detail only: UI
+// screenshots are not a merge gate, so it can never change a verdict.
+
+import type { ChangedFile } from "../orchestrator/diff";
+import type { CheckStatus } from "../orchestrator/checks";
+import { renderedLines } from "./code-review";
+
+const UI_EXT =
+  /\.(tsx|jsx|vue|svelte|astro|css|scss|sass|less|html|erb|haml|slim)$/i;
+const UI_DIR = /(^|\/)(app\/views|app\/components)\//;
+const SWIFT_VIEW = /(^|\/)(Views?\/.*|\w*Views?)\.swift$/;
+const NOT_UI = /(\.(test|spec|stories)\.|(^|\/)(__tests__|spec|tests?|e2e)\/)/;
+
+export function isUiPath(file: string): boolean {
+  if (NOT_UI.test(file)) return false;
+  return UI_EXT.test(file) || UI_DIR.test(file) || SWIFT_VIEW.test(file);
+}
+
+export function uiFilesIn(files: ChangedFile[]): string[] {
+  return files
+    .filter((f) => f.status !== "D" && isUiPath(f.path))
+    .map((f) => f.path);
+}
+
+const IMAGE =
+  /!\[|<img\b|\.(png|jpe?g|webp|gif)\b|user-images|githubusercontent/i;
+const DESCRIBED =
+  /browser check|simulator check|screenshot|chrome-devtools|viewports?\b|\b\d{3,4}\s*[x×]\s*\d{3,4}\b|in (a|the) (real )?browser|in the (ios )?simulator/i;
+
+// Lenient on purpose: a nudge, not a gate. Undefined when the body wasn't read.
+export function hasUiEvidence(
+  body: string | null | undefined
+): boolean | undefined {
+  if (body === null || body === undefined) return undefined;
+  return renderedLines(body).some((l) => IMAGE.test(l) || DESCRIBED.test(l));
+}
+
+export function uiEvidenceNote(
+  files: ChangedFile[],
+  evidence: boolean | undefined
+): string | null {
+  const ui = uiFilesIn(files);
+  if (!ui.length || evidence !== false) return null;
+  const shown = ui.slice(0, 3).join(", ");
+  const more = ui.length > 3 ? `, +${ui.length - 3} more` : "";
+  return `[minor] ${shown}${more}: this changes UI files and the PR body has no browser or simulator evidence (screenshots or a described check). Not a merge gate; add a Browser check section if you checked.`;
+}
+
+export function withUiEvidenceNote(
+  verdict: { status: CheckStatus; detail: string },
+  note: string | null
+): { status: CheckStatus; detail: string } {
+  return note
+    ? { status: verdict.status, detail: `${verdict.detail}\n- ${note}`.trim() }
+    : verdict;
+}

package/lib/tmux/exec.ts

@@ -1,5 +1,6 @@
 import { execFile } from "child_process";
 import { promisify } from "util";
+import { sessionBaseEnv } from "../agents/server-env";
 
 const execFileAsync = promisify(execFile);
 
@@ -9,6 +10,7 @@ export async function tmux(args: string[], timeout = 10_000): Promise<string> {
   const { stdout } = await execFileAsync("tmux", args, {
     timeout,
     maxBuffer: 8 << 20,
+    env: sessionBaseEnv(),
   });
   return stdout;
 }
@@ -24,7 +26,7 @@ export async function pasteText(
     const child = execFile(
       "tmux",
       ["load-buffer", "-b", buffer, "-"],
-      { timeout: 10_000 },
+      { timeout: 10_000, env: sessionBaseEnv() },
       (err) => (err ? reject(err) : resolve())
     );
     // tmux gone before it read everything is a failed paste, not a crash.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.659",
+  "version": "0.3.662",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"