feat(exec): accept a harness ARN for --harness (name|arn)

--harness now accepts a full harness ARN in addition to a name, matching
--runtime <name|arn>. A name is resolved to the harness ARN from deployed
state; an `arn:` value is used directly (with an `arn:` + --region
short-circuit that skips the config read, mirroring --runtime). A runtime
ARN passed to --harness is rejected with guidance to use --runtime, and a
full-ARN --harness skips the project requirement like --runtime does.

Also corrects the stale ExecOptions.harnessName doc comment (it resolves
to the harness ARN, not the underlying agentRuntimeArn).

Confidence: high
Scope-risk: narrow

Author: jesseturner21

src/cli/commands/exec/__tests__/action.test.ts

@@ -843,6 +843,39 @@ describe('loadExecContext with harnesses', () => {
     await expect(loadExecContext({ harnessName: 'nope' }, HARNESS_ONLY_CONFIG)).rejects.toThrow(/nope.*h1/);
   });
 
+  it('uses --harness <arn> directly with --region (no config read)', async () => {
+    // ARN + region short-circuits before any deployed-state lookup, mirroring --runtime <arn>.
+    const cfg = {
+      readAWSDeploymentTargets: vi.fn(),
+      readDeployedState: vi.fn(),
+    } as unknown as ConfigIO;
+
+    const ctx = await loadExecContext({ harnessName: HARNESS_ARN, region: 'us-west-2' }, cfg);
+    expect(ctx.runtimeArn).toBe(HARNESS_ARN);
+    expect(ctx.region).toBe('us-west-2'); // from the flag
+    expect(
+      (cfg as unknown as { readDeployedState: ReturnType<typeof vi.fn> }).readDeployedState
+    ).not.toHaveBeenCalled();
+  });
+
+  it('resolves region from config for --harness <arn> when --region is omitted', async () => {
+    const ctx = await loadExecContext({ harnessName: HARNESS_ARN }, HARNESS_ONLY_CONFIG);
+    expect(ctx.runtimeArn).toBe(HARNESS_ARN);
+    expect(ctx.region).toBe('us-east-1'); // from config target
+  });
+
+  it('rejects a runtime ARN passed to --harness (with --region)', async () => {
+    await expect(loadExecContext({ harnessName: HARNESS_RUNTIME_ARN, region: 'us-east-1' })).rejects.toThrow(
+      /--harness expects a harness ARN/
+    );
+  });
+
+  it('rejects a runtime ARN passed to --harness (no --region)', async () => {
+    await expect(loadExecContext({ harnessName: HARNESS_RUNTIME_ARN }, HARNESS_ONLY_CONFIG)).rejects.toThrow(
+      /--harness expects a harness ARN/
+    );
+  });
+
   it('throws no-target error when the only harness has no harness ARN in deployed state', async () => {
     const config = {
       readAWSDeploymentTargets: vi.fn().mockResolvedValue([{ name: 'default', region: 'us-east-1' }]),
@@ -995,6 +1028,12 @@ describe('loadExecContext interactive-harness guard', () => {
     );
   });
 
+  it('throws for --it with a harness ARN via --harness + --region', async () => {
+    await expect(loadExecContext({ interactive: true, harnessName: HARNESS_ARN, region: 'us-east-1' })).rejects.toThrow(
+      GUARD_MESSAGE
+    );
+  });
+
   it('does NOT block one-shot exec against a harness (interactive falsy)', async () => {
     const ctx = await loadExecContext({}, HARNESS_ONLY_CONFIG);
     expect(ctx.runtimeArn).toBe(HARNESS_ARN);

src/cli/commands/exec/action.ts

@@ -51,6 +51,16 @@ export async function loadExecContext(options: ExecOptions, configIO: ConfigIO =
     return assertInteractiveHarnessUnsupported(options, { region: options.region, runtimeArn: options.runtimeArn });
   }
 
+  // Same short-circuit for --harness <arn> + region. Validate it's a harness ARN (not a runtime ARN).
+  if (options.harnessName?.startsWith('arn:') && options.region) {
+    if (!isHarnessArn(options.harnessName)) {
+      throw new Error(
+        `--harness expects a harness ARN (…:harness/…), got '${options.harnessName}'. Use --runtime for a runtime ARN.`
+      );
+    }
+    return assertInteractiveHarnessUnsupported(options, { region: options.region, runtimeArn: options.harnessName });
+  }
+
   const awsTargets = await configIO.readAWSDeploymentTargets();
   const deployedState = await configIO.readDeployedState();
 
@@ -83,11 +93,24 @@ export async function loadExecContext(options: ExecOptions, configIO: ConfigIO =
     });
   }
 
-  // --harness <name>: resolve to the harness ARN.
+  // --harness <name|arn>: resolve to the harness ARN.
   // exec must target the harness ARN, NOT the underlying agentRuntimeArn: the data plane blocks
   // ExecuteCommand / shell against a harness-linked runtime ARN, but routes a harness ARN on the
   // /runtimes/{arn}/... path through the harness exec path (delegates to LoopyDP).
   if (options.harnessName) {
+    // A full ARN is used directly (must be a harness ARN, not a runtime ARN); a name is looked up.
+    if (options.harnessName.startsWith('arn:')) {
+      if (!isHarnessArn(options.harnessName)) {
+        throw new Error(
+          `--harness expects a harness ARN (…:harness/…), got '${options.harnessName}'. Use --runtime for a runtime ARN.`
+        );
+      }
+      return assertInteractiveHarnessUnsupported(options, {
+        region: options.region ?? targetConfig.region,
+        runtimeArn: options.harnessName,
+      });
+    }
+
     const harnessState = targetState?.resources?.harnesses?.[options.harnessName];
     if (!harnessState) {
       throw new Error(

src/cli/commands/exec/command.tsx

@@ -32,7 +32,7 @@ export const registerExec = (program: Command) => {
     .argument('[command...]', 'Command to execute (one-shot mode, non-interactive)')
     .option('--it', 'Open an interactive PTY shell session')
     .option('--runtime <name|arn>', 'Target agent name or runtime ARN (skips agent picker)')
-    .option('--harness <name>', 'Target harness name (skips agent picker)')
+    .option('--harness <name|arn>', 'Target harness name or harness ARN (skips agent picker)')
     .option('--session-id <id>', 'Pin to a specific runtime session / VM')
     .option('--shell-id <id>', 'Reconnect to an existing shell')
     .option('--region <region>', 'AWS region')
@@ -57,10 +57,12 @@ export const registerExec = (program: Command) => {
         }
       ) => {
         try {
-          // Skip project check only when --runtime is a full ARN: the user has all the
+          // Skip project check only when --runtime or --harness is a full ARN: the user has all the
           // information they need without an agentcore.json in the working directory.
-          // A name-based --runtime still requires the project to resolve the ARN.
-          if (!cliOptions.runtime?.startsWith('arn:')) {
+          // A name-based --runtime/--harness still requires the project to resolve the ARN.
+          const hasArnTarget =
+            Boolean(cliOptions.runtime?.startsWith('arn:')) || Boolean(cliOptions.harness?.startsWith('arn:'));
+          if (!hasArnTarget) {
             if (cliOptions.json) {
               // requireProject() renders Ink and calls process.exit — bypass it in JSON mode
               // so we can emit a machine-readable error instead.

src/cli/commands/exec/types.ts

@@ -3,7 +3,8 @@ import type { Result } from '../../../lib/result';
 export interface ExecOptions {
   /** Target runtime ARN (from --runtime). Skips agent picker when provided. */
   runtimeArn?: string;
-  /** Target harness name (from --harness). Resolves to the harness's underlying runtime ARN. */
+  /** Target harness name or harness ARN (from --harness). A name is resolved to the harness ARN
+   *  from deployed state; a full `arn:` value is used directly. Skips agent picker when provided. */
   harnessName?: string;
   /** Routes the connection to a specific VM (from --session-id). */
   sessionId?: string;