fix: defer policy engine write and harden policy flow UX (#856)

* fix: defer policy engine write to disk until flow completes

Previously, pressing Escape on the gateway selection screen during
policy engine creation would skip to the success screen because the
engine was already written to agentcore.json at the name step. Now
the disk write is deferred until the user completes the entire flow,
so Escape correctly navigates back to the previous step without
persisting a half-configured engine.

Constraint: Must not break non-interactive CLI path which still writes immediately via primitive
Rejected: Only change Escape to go back without deferring write | engine would still be persisted on back
Confidence: high
Scope-risk: narrow

* fix: preserve engine name when navigating back from gateway selection

When pressing Escape on the gateway screen to go back to the name step,
the previously entered engine name was lost because AddPolicyEngineScreen
remounted with a generated default. Now the entered name is stored in
pendingEngineName state and passed back as initialName so the user sees
their original input.

Constraint: Must not change flow state union type to keep diff minimal
Rejected: Carry name in FlowState union variant | adds complexity to type for one field
Confidence: high
Scope-risk: narrow

* chore: remove TUI harness test accidentally committed

This test requires a live terminal session and cannot run as a unit test
in CI. It was an untracked local file that got staged by mistake.

Author: jesseturner21

src/cli/tui/screens/policy/AddPolicyEngineScreen.tsx

@@ -9,13 +9,15 @@ interface AddPolicyEngineScreenProps {
   onComplete: (config: AddPolicyEngineConfig) => void;
   onExit: () => void;
   existingEngineNames: string[];
+  initialName?: string;
   headerContent?: React.ReactNode;
 }
 
 export function AddPolicyEngineScreen({
   onComplete,
   onExit,
   existingEngineNames,
+  initialName,
   headerContent,
 }: AddPolicyEngineScreenProps) {
   return (
@@ -24,7 +26,7 @@ export function AddPolicyEngineScreen({
         <TextInput
           key="name"
           prompt="Policy engine name"
-          initialValue={generateUniqueName('MyPolicyEngine', existingEngineNames)}
+          initialValue={initialName ?? generateUniqueName('MyPolicyEngine', existingEngineNames)}
           onSubmit={name => onComplete({ name })}
           onCancel={onExit}
           schema={PolicyEngineNameSchema}

src/cli/tui/screens/policy/AddPolicyFlow.tsx

@@ -56,6 +56,7 @@ export function AddPolicyFlow({ isInteractive = true, onExit, onBack, onDev, onD
   const [engineNames, setEngineNames] = useState<string[]>([]);
   const [policyNames, setPolicyNames] = useState<string[]>([]);
   const [hasUnprotectedGateways, setHasUnprotectedGateways] = useState(false);
+  const [pendingEngineName, setPendingEngineName] = useState<string | undefined>();
 
   const engineSteps = useMemo<EngineCreationStep[]>(() => {
     const steps: EngineCreationStep[] = ['name'];
@@ -126,23 +127,32 @@ export function AddPolicyFlow({ isInteractive = true, onExit, onBack, onDev, onD
     }
   }, []);
 
-  const handleEngineComplete = useCallback(async (config: AddPolicyEngineConfig) => {
-    const result = await policyEnginePrimitive.add({
-      name: config.name,
-    });
+  const commitEngine = useCallback(async (engineName: string, gateways?: string[], mode?: 'LOG_ONLY' | 'ENFORCE') => {
+    const result = await policyEnginePrimitive.add({ name: engineName });
+    if (!result.success) {
+      setFlow({ name: 'error', message: result.error });
+      return;
+    }
+    setEngineNames(prev => [...prev, engineName]);
+    setPendingEngineName(undefined);
+    if (gateways && gateways.length > 0 && mode) {
+      await policyEnginePrimitive.attachToGateways(engineName, gateways, mode);
+    }
+    setFlow({ name: 'engine-success', engineName });
+  }, []);
 
-    if (result.success) {
-      setEngineNames(prev => [...prev, config.name]);
+  const handleEngineComplete = useCallback(
+    async (config: AddPolicyEngineConfig) => {
+      setPendingEngineName(config.name);
       const unprotected = await policyEnginePrimitive.getUnprotectedGateways();
       if (unprotected.length > 0) {
         setFlow({ name: 'attach-gateways', engineName: config.name, gateways: unprotected });
       } else {
-        setFlow({ name: 'engine-success', engineName: config.name });
+        void commitEngine(config.name);
       }
-    } else {
-      setFlow({ name: 'error', message: result.error });
-    }
-  }, []);
+    },
+    [commitEngine]
+  );
 
   const handlePolicyComplete = useCallback(async (config: AddPolicyConfig) => {
     const result = await policyPrimitive.add({
@@ -201,6 +211,7 @@ export function AddPolicyFlow({ isInteractive = true, onExit, onBack, onDev, onD
     return (
       <AddPolicyEngineScreen
         existingEngineNames={engineNames}
+        initialName={pendingEngineName}
         headerContent={<StepIndicator steps={engineSteps} currentStep="name" labels={ENGINE_STEP_LABELS} />}
         onComplete={(config: AddPolicyEngineConfig) => void handleEngineComplete(config)}
         onExit={() => {
@@ -238,7 +249,7 @@ export function AddPolicyFlow({ isInteractive = true, onExit, onBack, onDev, onD
         stepIndicator={<StepIndicator steps={engineSteps} currentStep="attach-gateways" labels={ENGINE_STEP_LABELS} />}
         onConfirm={selected => {
           if (selected.length === 0) {
-            setFlow({ name: 'engine-success', engineName: flow.engineName });
+            void commitEngine(flow.engineName);
           } else {
             setFlow({
               name: 'attach-mode',
@@ -248,7 +259,7 @@ export function AddPolicyFlow({ isInteractive = true, onExit, onBack, onDev, onD
             });
           }
         }}
-        onSkip={() => setFlow({ name: 'engine-success', engineName: flow.engineName })}
+        onBack={() => setFlow({ name: 'engine-wizard' })}
       />
     );
   }
@@ -261,15 +272,12 @@ export function AddPolicyFlow({ isInteractive = true, onExit, onBack, onDev, onD
         gatewayCount={flow.selectedGateways.length}
         stepIndicator={<StepIndicator steps={engineSteps} currentStep="attach-mode" labels={ENGINE_STEP_LABELS} />}
         onSelect={mode => {
-          void policyEnginePrimitive
-            .attachToGateways(flow.engineName, flow.selectedGateways, mode)
-            .then(() => setFlow({ name: 'engine-success', engineName: flow.engineName }))
-            .catch(err =>
-              setFlow({
-                name: 'error',
-                message: err instanceof Error ? err.message : 'Failed to attach policy engine',
-              })
-            );
+          void commitEngine(flow.engineName, flow.selectedGateways, mode).catch(err =>
+            setFlow({
+              name: 'error',
+              message: err instanceof Error ? err.message : 'Failed to attach policy engine',
+            })
+          );
         }}
         onBack={() => {
           setFlow({ name: 'attach-gateways', engineName: flow.engineName, gateways: flow.allGateways });
@@ -360,13 +368,13 @@ function AttachGatewaysScreen({
   engineName,
   gateways,
   onConfirm,
-  onSkip,
+  onBack,
   stepIndicator,
 }: {
   engineName: string;
   gateways: string[];
   onConfirm: (selected: string[]) => void;
-  onSkip: () => void;
+  onBack: () => void;
   stepIndicator?: React.ReactNode;
 }) {
   const items: SelectableItem[] = useMemo(() => gateways.map(name => ({ id: name, title: name })), [gateways]);
@@ -375,16 +383,16 @@ function AttachGatewaysScreen({
     items,
     getId: item => item.id,
     onConfirm: ids => onConfirm([...ids]),
-    onExit: onSkip,
+    onExit: onBack,
     isActive: true,
     requireSelection: false,
   });
 
   return (
     <Screen
       title="Attach Policy Engine"
-      onExit={onSkip}
-      helpText="Space toggle · Enter confirm · Esc skip · Ctrl+C quit"
+      onExit={onBack}
+      helpText="Space toggle · Enter confirm · Esc back · Ctrl+C quit"
       headerContent={stepIndicator}
     >
       <Panel>