Add dedicated environment settings page and test-in-environment (#4798)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies
> - Agents run inside environments (local, SSH, E2B sandbox)
> - Operators need to configure and manage these environments
> - But environment settings were buried inside the general company
settings page, making them hard to find
> - Additionally, when testing an agent from the configuration form, the
test always ran locally regardless of which environment was selected
> - This PR moves environments into a dedicated top-level company
settings section and wires the "Test Environment" button to run inside
the selected environment
> - The benefit is operators can find and manage environments more
easily, and the test button now validates the actual environment the
agent will use

## What Changed

- Added a dedicated `CompanyEnvironments` settings page with its own
route and sidebar entry
- Updated `CompanySettingsSidebar` and `CompanySettingsNav` to include
the new environments section
- Modified the agent test route (`POST /agents/:id/test`) to accept an
optional `environmentId` parameter
- Updated all adapter `test.ts` handlers to resolve and use the
specified execution target environment
- Added `resolveTestExecutionTarget` to `execution-target.ts` for remote
environment test resolution with cwd fallback
- Moved the "Test Environment" button and its feedback display into the
`NewAgent` page footer for better UX flow

## Verification

- `pnpm test` — all existing and new tests pass
- `pnpm typecheck` — clean
- Manual: navigate to Company Settings, confirm "Environments" appears
as a top-level section
- Manual: configure an agent with a non-local environment, click "Test
Environment", confirm the test runs inside that environment

## Risks

- Low risk. UI-only routing change for the settings page. The
test-in-environment change adds an optional parameter with a local
fallback, so existing behavior is preserved when no environment is
specified.

## Model Used

Codex GPT 5.4 high via Paperclip.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

packages/adapter-utils/src/execution-target.test.ts

@@ -2,6 +2,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import * as ssh from "./ssh.js";
 import {
   adapterExecutionTargetUsesManagedHome,
+  resolveAdapterExecutionTargetCwd,
   runAdapterExecutionTargetShellCommand,
 } from "./execution-target.js";
 
@@ -159,3 +160,49 @@ describe("runAdapterExecutionTargetShellCommand", () => {
     })).toBe(false);
   });
 });
+
+describe("resolveAdapterExecutionTargetCwd", () => {
+  const sshTarget = {
+    kind: "remote" as const,
+    transport: "ssh" as const,
+    remoteCwd: "/srv/paperclip/workspace",
+    spec: {
+      host: "ssh.example.test",
+      port: 22,
+      username: "ssh-user",
+      remoteCwd: "/srv/paperclip/workspace",
+      remoteWorkspacePath: "/srv/paperclip/workspace",
+      privateKey: null,
+      knownHosts: null,
+      strictHostKeyChecking: true,
+    },
+  };
+
+  it("falls back to the remote cwd when no adapter cwd is configured", () => {
+    expect(resolveAdapterExecutionTargetCwd(sshTarget, "", "/Users/host/repo/server")).toBe(
+      "/srv/paperclip/workspace",
+    );
+    expect(resolveAdapterExecutionTargetCwd(sshTarget, "   ", "/Users/host/repo/server")).toBe(
+      "/srv/paperclip/workspace",
+    );
+    expect(resolveAdapterExecutionTargetCwd(sshTarget, null, "/Users/host/repo/server")).toBe(
+      "/srv/paperclip/workspace",
+    );
+  });
+
+  it("preserves an explicit adapter cwd when one is configured", () => {
+    expect(
+      resolveAdapterExecutionTargetCwd(
+        sshTarget,
+        "/srv/paperclip/custom-agent-dir",
+        "/Users/host/repo/server",
+      ),
+    ).toBe("/srv/paperclip/custom-agent-dir");
+  });
+
+  it("keeps the local fallback cwd for local targets", () => {
+    expect(resolveAdapterExecutionTargetCwd(null, "", "/Users/host/repo/server")).toBe(
+      "/Users/host/repo/server",
+    );
+  });
+});

packages/adapter-utils/src/execution-target.ts

@@ -130,6 +130,17 @@ export function adapterExecutionTargetRemoteCwd(
   return target?.kind === "remote" ? target.remoteCwd : localCwd;
 }
 
+export function resolveAdapterExecutionTargetCwd(
+  target: AdapterExecutionTarget | null | undefined,
+  configuredCwd: string | null | undefined,
+  localFallbackCwd: string,
+): string {
+  if (typeof configuredCwd === "string" && configuredCwd.trim().length > 0) {
+    return configuredCwd;
+  }
+  return adapterExecutionTargetRemoteCwd(target, localFallbackCwd);
+}
+
 export function adapterExecutionTargetPaperclipApiUrl(
   target: AdapterExecutionTarget | null | undefined,
 ): string | null {
@@ -336,6 +347,64 @@ export async function ensureAdapterExecutionTargetFile(
   );
 }
 
+/**
+ * Ensure a working directory exists (and is a directory) on the execution target.
+ *
+ * For local targets this delegates to the local `ensureAbsoluteDirectory` helper
+ * (Node fs). For remote (SSH/sandbox) targets it shells out and runs
+ * `mkdir -p` (when allowed) followed by a `[ -d ]` check so the result reflects
+ * the directory state inside the environment, not on the Paperclip host.
+ *
+ * Throws an Error with a human-readable message on failure.
+ */
+export async function ensureAdapterExecutionTargetDirectory(
+  runId: string,
+  target: AdapterExecutionTarget | null | undefined,
+  cwd: string,
+  options: AdapterExecutionTargetShellOptions & { createIfMissing?: boolean },
+): Promise<void> {
+  const createIfMissing = options.createIfMissing ?? false;
+
+  if (!target || target.kind === "local") {
+    const { ensureAbsoluteDirectory } = await import("./server-utils.js");
+    await ensureAbsoluteDirectory(cwd, { createIfMissing });
+    return;
+  }
+
+  // Remote (SSH or sandbox): both expect POSIX absolute paths inside the env.
+  if (!cwd.startsWith("/")) {
+    throw new Error(`Working directory must be an absolute POSIX path on the remote target: "${cwd}"`);
+  }
+
+  const quoted = shellQuote(cwd);
+  const script = createIfMissing
+    ? `mkdir -p ${quoted} && [ -d ${quoted} ]`
+    : `[ -d ${quoted} ]`;
+
+  const result = await runAdapterExecutionTargetShellCommand(runId, target, script, {
+    cwd: target.kind === "remote" ? target.remoteCwd : cwd,
+    env: options.env,
+    timeoutSec: options.timeoutSec ?? 15,
+    graceSec: options.graceSec ?? 5,
+    onLog: options.onLog,
+  });
+
+  if (result.timedOut) {
+    throw new Error(`Timed out checking working directory on remote target: "${cwd}"`);
+  }
+  if ((result.exitCode ?? 1) !== 0) {
+    const detail = (result.stderr || result.stdout || "").trim();
+    if (createIfMissing) {
+      throw new Error(
+        `Could not create working directory "${cwd}" on remote target${detail ? `: ${detail}` : "."}`,
+      );
+    }
+    throw new Error(
+      `Working directory does not exist on remote target: "${cwd}"${detail ? ` (${detail})` : ""}`,
+    );
+  }
+}
+
 export function adapterExecutionTargetSessionIdentity(
   target: AdapterExecutionTarget | null | undefined,
 ): Record<string, unknown> | null {

packages/adapter-utils/src/types.ts

@@ -216,6 +216,20 @@ export interface AdapterEnvironmentTestContext {
   companyId: string;
   adapterType: string;
   config: Record<string, unknown>;
+  /**
+   * Optional execution target the adapter should run probes against.
+   *
+   * If omitted (or `kind === "local"`), the adapter tests on the Paperclip
+   * host. For SSH/sandbox targets the adapter should run command/auth probes
+   * inside the remote environment so the result reflects what an agent run
+   * would actually see at execution time.
+   */
+  executionTarget?: AdapterExecutionTarget | null;
+  /**
+   * Friendly name of the environment being tested (when `executionTarget` is set).
+   * Surfaced in check messages so users see which environment the probe ran in.
+   */
+  environmentName?: string | null;
   deployment?: {
     mode?: "local_trusted" | "authenticated";
     exposure?: "private" | "public";